ptpd2.conf(5)

📦 version 2.3.1, in opensuse-leap 16.0

Bestie, welcome to ptpd2.conf(5) — aka the PTPd config file manual — and it’s literally the config file for the Precision Time Protocol daemon. We’re making it make sense. ✨

💖 NAME 💖

ptpd2.conf — Precision Time Protocol daemon config file.

🎀 CONFIGURATION FILE FORMAT 🎀

Settings in the PTPd configuration file are grouped into sections and take the form of section:key="value" variables. The config file can either be formatted that way (preferred, slay) or in .ini file style, where a series of key="value" variables is grouped into sections using [section] headers. Every setting listed here can also be specified as a command line parameter: --section:key=value. Quotation marks are optional.

NOTE: the configuration file must end with a newline. 💀

🔄 RELOADING CONFIGURATION 🔄

Only a small number of configuration file settings — SNMP and lock file configuration — require a restart of the PTPd process to take effect. All the other settings can be changed while ptpd is running: the configuration file is reloaded and checked for changes when PTPd receives the SIGHUP signal.

When reloading configuration, PTPd will always attempt to test settings before applying them, and once it’s running it will never exit as a result of configuration errors. If it does exit during a config refresh, that’s most likely a bug. 😭

👑 PRIORITY 👑

Any setting passed as a command line parameter will always take priority over the configuration file. So once ptpd is running, those settings cannot be changed — a warning will be logged on every attempt to change those settings using the configuration file. Periodt. ⚠️

🌈 CONFIGURATION SECTIONS 🌈

  • ptpengine — PTP protocol specific configuration
  • clock — Clock related settings
  • servo — Clock control PI servo configuration
  • global — Global configuration - logging, etc.
  • ntpengine — NTP control configuration

🦋 CONFIGURATION VARIABLES 🦋

Here come the variables, bestie — no skipping. 🫶

  • ptpengine:interface [STRING]
    • usage: Network interface to use — eth0, igb0 etc. (required).
    • default: [none]
  • ptpengine:backup_interface [STRING]
    • usage: Backup network interface to use — eth0, igb0 etc. When no GM is available, the slave will keep alternating between primary and secondary until a GM is found.
    • default: [none]
  • ptpengine:preset [SELECT]
    • options: none, slaveonly, masteronly, masterslave
    • usage: PTP engine preset:
      • none — Defaults, no clock class restrictions
      • slaveonly — Slave only (clock class 255 only)
      • masteronly — Master, passive when not best master (clock class 0..127)
      • masterslave — Full IEEE 1588 implementation: Master, slave when not best master (clock class 128..254)
    • default: slaveonly
    • NOTE: Presets affect the following settings: ptpengine:slave_only, clock_no_adjust and ptpengine:clock_class (range and default value). To see all preset settings, run ptpd2 -H (--long-help).
  • ptpengine:transport [SELECT]
    • options: ipv4, ethernet
    • usage: Transport type for PTP packets. NOTE: Ethernet transport requires building with libpcap and is not supported on Solaris as of 2.3.1, and cannot be enabled on those systems unless ptpd is compiled with --enable-experimental-options.
    • default: ipv4
  • ptpengine:dot2as [BOOLEAN]
    • usage: Enable IEEE 802.1AS / AVB compatibility (transportSpecific field in PTP message headers). Requires Ethernet transport as this is the only mapping used by 802.1AS that PTP supports.
    • default: N
  • ptpengine:ip_mode [SELECT]
    • options: multicast, unicast, hybrid
    • usage: IP transmission mode (requires IP transport):
      • multicast — uses multicast for all messages
      • hybrid — uses multicast for sync and announce, and unicast for delay request and response
      • unicast — uses unicast for all transmission. When unicast mode is selected, destination IP(s) (ptpengine:unicast_destinations) must be configured depending on unicast negotiation setting (ptpengine:unicast_negotiation) and master or slave role (see: ptpengine:unicast_destinations)
    • default: multicast
  • ptpengine:unicast_negotiation [BOOLEAN]
    • usage: Enable unicast negotiation support using signaling messages — as used by the Telecom profile (ITU-T G.8265.1).
    • default: N
  • ptpengine:unicast_grant_duration [INT: 30 .. 604800]
    • usage: Duration (seconds) for which the transmission of unicast messages is granted by a master, or requested by a slave when unicast negotiation is used (ptpengine:unicast_negotiation). When using PTPd with other PTP implementations, PTPd will never refuse to grant a message based on the requested duration: it will grant for 30 seconds if requested for any less than 30 seconds, and will grant for 7 days (604800) if requested for any longer.
    • default: 300
  • ptpengine:disable_bmca [BOOLEAN]
    • usage: Disable Best Master Clock Algorithm for unicast masters. Only effective for masteronly preset — all Announce messages will be ignored and the cock will transition directly into MASTER state and remain an active master. This behaviour is required for Telecom profile operation.
    • default: N
  • ptpengine:use_libpcap [BOOLEAN]
    • usage: Use libpcap for sending and receiving traffic (automatically enabled in Ethernet mode). Requires building with libpcap — builds made with --disable-pcap cannot use this feature, and as of 2.3.1, Solaris systems will not attempt to use libpcap unless compiled with --enable-experimental-options.
    • default: N
  • ptpengine:delay_mechanism [SELECT]
    • options: E2E, P2P, DELAY_DISABLED
    • usage: Delay detection mode used — use DELAY_DISABLED for syntonisation only (no synchronisation).
    • default: E2E
  • ptpengine:domain [INT: 0 .. 127]
    • usage: PTP domain number.
    • default: 0
  • ptpengine:any_domain [BOOLEAN]
    • usage: Usability extension: if enabled, a slave-only clock will accept masters from any domain, while preferring the configured domain, and preferring lower domain number. This option should be used for slave-only clocks and should not be used with unicast negotiation. NOTE: this behaviour is not part of the standard.
    • default: N
  • ptpengine:port_number [INT: 1 .. 65534]
    • usage: PTP port number (part of PTP Port Identity — not UDP port). For ordinary clocks (single port), the default should be used, but when running multiple instances to simulate a boundary clock, The port number can be changed.
    • default: 1
  • ptpengine:slave_only [BOOLEAN]
    • usage: Slave only mode (sets clock class to 255, overriding value from preset).
    • default: Y
  • ptpengine:inbound_latency [INT]
    • usage: Specify latency correction (nanoseconds) for incoming packets.
    • default: 0
  • ptpengine:outbound_latency [INT]
    • usage: Specify latency correction (nanoseconds) for outgoing packets.
    • default: 0
  • ptpengine:offset_shift [INT]
    • usage: Apply an arbitrary shift (nanoseconds) to offset from master when in slave state. Value can be positive or negative — useful for correcting for of antenna latencies, delay assymetry and IP stack latencies. This will not be visible in the offset from master value — only in the resulting clock correction.
    • default: 0
  • ptpengine:always_respect_utc_offset [BOOLEAN]
    • usage: Compatibility option: In slave state, always respect UTC offset announced by best master, even if the the currrentUtcOffsetValid flag is announced FALSE. NOTE: this behaviour is not part of the standard.
    • default: N
  • ptpengine:prefer_utc_offset_valid [BOOLEAN]
    • usage: Compatibility extension to BMC algorithm: when enabled, BMC for both master and save clocks will prefer masters announcing currrentUtcOffsetValid as TRUE. NOTE: this behaviour is not part of the standard.
    • default: N
  • ptpengine:require_utc_offset_valid [BOOLEAN]
    • usage: Compatibility option: when enabled, ptpd2 will ignore Announce messages from masters announcing currentUtcOffsetValid as FALSE. NOTE: this behaviour is not part of the standard.
    • default: N
  • ptpengine:log_announce_interval [INT: -4 .. 7]
    • usage: PTP announce message interval in master state. When using unicast negotiation (ptpengine:unicast_negotiation), for slaves this is the initial (minimum) interval requested and for masters this is the minimum interval granted. (expressed as log 2 i.e. -1=0.5s, 0=1s, 1=2s etc.)
    • default: 1
  • ptpengine:log_announce_interval_max [INT: -1 .. 7]
    • usage: When using unicast negtiation (ptpengine:unicast_negotiation), this is the maximum announce interval granted by a master, and the maximum interval a slave will attempt to request. (expressed as log 2 i.e. -1=0.5s, 0=1s, 1=2s etc.)
    • default: 5
  • ptpengine:announce_receipt_timeout [INT: 2 .. 255]
    • usage: PTP announce receipt timeout announced in master state.
    • default: 6
  • ptpengine:announce_receipt_grace_period [INT: 0 .. 20]

…okay so picking right back up on the grace-period one whose header is sitting at the bottom of the last chunk 🫶 — here's the tea: it's the PTP announce receipt timeout grace period, and it does its thing in slave state. When an announce receipt timeout goes down, ptpd disqualifies the current best GM, and then it waits n times the announce receipt timeout before resetting. That's literally what buys you a seamless GM failover when your standby GMs are being slow to react 🐢. Set it to 0 and this option just isn't used.

default: 0

  • ptpengine:log_sync_interval [INT: -7 .. 7] — the PTP sync message interval when you're in master state. When unicast negotiation is on (ptpengine:unicast_negotiation): for slaves this is the initial (minimum) interval they request, and for masters it's the minimum interval they grant. (Expressed as log 2, i.e. -1=0.5s, 0=1s, 1=2s etc.) default 0.
  • ptpengine:log_sync_interval_max [INT: -1 .. 7] — when unicast negotiation is on (ptpengine:unicast_negotiation), this is the maximum sync interval a master grants and the maximum interval a slave will even attempt to request. (Log 2 again, bestie: -1=0.5s, 0=1s, 1=2s etc.) default 5.
  • ptpengine:log_delayreq_override [BOOLEAN] — overrides the Delay Request interval that the best master hands you 👑. default N.
  • ptpengine:log_delayreq_auto [BOOLEAN] — automatically overrides the Delay Request interval (using ptpengine:log_delayreq_interval) whenever the value you received is 127 (0X7F), like in unicast messages — unless you're running unicast negotiation (ptpengine:unicast_negotiation). default Y.
  • ptpengine:log_delayreq_interval_initial [INT: -7 .. 7] — the delay request interval used before you receive your first delay response. (Log 2: -1=0.5s, 0=1s, 1=2s etc.) default 0.
  • ptpengine:log_delayreq_interval [INT: -7 .. 7] — the minimum delay request interval announced in master state; in slave state it overrides the master's interval. (Log 2: -1=0.5s, 0=1s, 1=2s etc.) With unicast negotiation (ptpengine:unicast_negotiation): for slaves this is the initial (minimum) interval requested, for masters the minimum interval granted. default 0.
  • ptpengine:log_delayreq_interval_max [INT: -1 .. 7] — with unicast negotiation (ptpengine:unicast_negotiation), this is the maximum delay request interval a master grants, and the maximum a slave will attempt to request. (Log 2: -1=0.5s, 0=1s, 1=2s etc.) default 5.
  • ptpengine:log_peer_delayreq_interval [INT: -7 .. 7] — the minimum peer delay request message interval in peer-to-peer delay mode (log 2: -1=0.5s, 0=1s, 1=2s etc.). With unicast negotiation (ptpengine:unicast_negotiation), this is the initial (minimum) interval a node requests from its peer, and the minimum interval granted for a peer 🫱🫲. default 1.
  • ptpengine:log_peer_delayreq_interval_max [INT: -1 .. 7] — with unicast negotiation (ptpengine:unicast_negotiation), this is the maximum peer delay request interval granted by a node, and the maximum a node will attempt to request from its peer. (Log 2: -1=0.5s, 0=1s, 1=2s etc.) default 5.
  • ptpengine:foreignrecord_capacity [INT: 5 .. 10] — the foreign master record size, aka the maximum number of foreign masters. default 5.
  • ptpengine:ptp_allan_variance [INT: 0 .. 65535] — the Allan variance announced in master state. default 28768.
  • ptpengine:ptp_clock_accuracy [SELECT] — the clock accuracy range announced in master state. Your options are ACC_25NS, ACC_100NS, ACC_250NS, ACC_1US, ACC_2.5US, ACC_10US, ACC_25US, ACC_100US, ACC_250US, ACC_1MS, ACC_2.5MS, ACC_10MS, ACC_25MS, ACC_100MS, ACC_250MS, ACC_1S, ACC_10S, ACC_10SPLUS, ACC_UNKNOWN. default ACC_UNKNOWN (very "I'll figure it out later" of you 🙈).
  • ptpengine:utc_offset [INT] — the underlying time source UTC offset announced in master state. default 0.
  • ptpengine:utc_offset_valid [BOOLEAN] — whether that underlying time source UTC offset is valid, announced in master state. default N.
  • ptpengine:time_traceable [BOOLEAN] — the underlying time source's time traceability, announced in master state. default N.
  • ptpengine:frequency_traceable [BOOLEAN] — same energy, but for the underlying time source's frequency traceability, announced in master state. default N.
  • ptpengine:ptp_timescale [SELECT] — options PTP and ARB. It's the time scale announced in master state (with ARB, UTC properties are ignored by slaves, just so you know 👀). When clock class is set to 13 (application specific), this value is ignored and ARB is used. default ARB.
  • ptpengine:ptp_timesource [SELECT] — options ATOMIC_CLOCK, GPS, TERRESTRIAL_RADIO, PTP, NTP, HAND_SET, OTHER, INTERNAL_OSCILLATOR. The time source announced in master state ⭐. default INTERNAL_OSCILLATOR.
  • ptpengine:clock_class [INT: 0 .. 255] — the clock class, announced in master state. It's always 255 for slave-only. The minimum, maximum and default values are controlled by presets. If you set it to 13 (application specific time source), the announced time scale is always set to ARB, periodt. This setting also controls which states a PTP port can be in: below 128, the port will only ever be in MASTER or PASSIVE states (master only); above 127, the port will be in MASTER or SLAVE states. default 255.
  • ptpengine:priority1 [INT: 0 .. 248] — Priority 1 announced in master state, used for Best Master Clock selection 👑. default 128.
  • ptpengine:priority2 [INT: 0 .. 248] — Priority 2 announced in master state, also used for Best Master Clock selection. default 128.
  • ptpengine:max_listen [INT: min: 1] — how many consecutive protocol resets to LISTENING you get before a full network reset. default 5.
  • ptpengine:unicast_destinations [STRING] — an IPv4 address, or a whole list of IPv4 addresses, to be used as unicast destinations. When unicast negotiation (ptpengine:unicast_negotiation) is enabled, setting this is mandatory for slaves, because they have to know which GMs to request messages from. When unicast negotiation is disabled, setting this is mandatory for GMs, because they have to deliver messages to a pre-configured group of slaves. default [none].
  • ptpengine:unicast_domains [STRING] — the PTP domain number for each configured unicast destination (ptpengine:unicast_destinations). Only used by slave-only clocks that use unicast destinations, so that each master can sit in a separate domain — like with Telecom Profile 📞. The number of entries should match the number of unicast destinations; otherwise unconfigured domains, or domains set to 0, get set to the domain configured in ptpengine:domain. Format is a comma, tab or space-separated list of 8-bit unsigned integers (0 .. 255). default [none].
  • ptpengine:unicast_local_preference [STRING] — a local preference for each configured unicast destination (ptpengine:unicast_destinations). Only used by slave-only clocks using unicast destinations, so the slave can locally influence each master's BMC selection — Telecom Profile vibes again 💅. The number of entries should match the number of unicast destinations; otherwise the unconfigured preference gets set to 0 (highest). Format is a comma, tab or space-separated list of 8-bit unsigned integers (0 .. 255). default [none].
  • ptpengine:unicast_peer_destination [STRING] — when you're using IP unicast mode (ptpengine:ip_mode=unicast) together with the Peer to Peer delay mechanism (ptpengine:delay_mechanism=P2P), you must configure a peer unicast destination to request the peer delay from. Format is a single unicast IPv4 address. default [none].
  • ptpengine:management_enable [BOOLEAN] — enables handling of PTP management messages. Only GET messages get processed by default. See ptpengine:management_set_enable 👀. default Y.
  • ptpengine:management_set_enable [BOOLEAN] — accepts SET and COMMAND management messages. default N.
  • ptpengine:igmp_refresh [BOOLEAN] — sends explicit IGMP joins between engine resets, and periodically while in master state. default Y.
  • ptpengine:master_igmp_refresh_interval [INT: 0 .. 255] — the periodic IGMP join interval (seconds) in master state when running IPv4 multicast. When it's set below 10, or when ptpengine:igmp_refresh is disabled, this setting has no effect 🫥. default 60.
  • ptpengine:multicast_ttl [INT: 1 .. 64] — multicast time to live for multicast PTP packets (ignored and set to 1 for peer to peer messages). default 64.
  • ptpengine:ip_dscp [INT: 0 .. 63] — the DiffServ Codepoint for packet prioritisation (decimal). When it's set to zero, this option isn't used. Use 46 for Expedited Forwarding (0x2e) 🔥. default 0.
  • ptpengine:sync_stat_filter_enable [BOOLEAN] — okay so this is exactly where our chunk runs out 😭 the rest of this one (its usage and its default) is waiting for you in part three, bestie — go go go 🏃‍♀️💨
  • usage — flips on the statistical filter for Sync messages. default N 😴 (so like, off unless you say otherwise)
  • ptpengine:sync_stat_filter_type [SELECT] — which flavor of filtering we're doing on Sync messages, bestie. pick one:
    • options: none mean min max absmin absmax median
    • none — no filtering at all, pure pass-through, the vibe is "I trust the packets" 🫶
    • mean — mean (average); smooths things out but lowkey gets dragged around by outliers 😭
    • min — the minimal value; iconic when packet delay variation is high (we call those "lucky packets" ✨)
    • max — the maximal value; perfect for testing worst-case scenarios 💀
    • absmin — absolute minimum, i.e. the value closest to zero. also great for test purposes 🧪
    • absmax — absolute maximun value farthest away from zero 👑
    • median — median (middle value); more robust than mean, and not influenced by outliers 🌸
    • default min
  • ptpengine:sync_stat_filter_window [INT: 3 .. 128] — how many samples the Sync statistical filter chews on. default 4 🍓
  • ptpengine:sync_stat_filter_window_type [SELECT] — how the sampling window behaves for the Sync statistical filter:
    • options: sliding interval
    • sliding — sliding window; a value comes out every time the filter runs, which can result in duplicates 🙈
    • interval — only output a value every n-th sample (full window); independent sampling periods 🎀
    • default sliding
  • ptpengine:delay_stat_filter_enable [BOOLEAN] — turns on the statistical filter for Delay messages. default N
  • ptpengine:delay_stat_filter_type [SELECT] — the filter type used for Delay message filtering, same menu as before:
    • options: none mean min max absmin absmax median
    • none — no filtering, pass-through, we're raw-dogging the data 💅
    • mean — mean (average); smooth results but influenced by outliers
    • min — minimal value; useful for high packet delay variation ("lucky packets")
    • max — maximal value; useful for testing worst case scenarios
    • absmin — absolute minimum, value closest to zero. also useful for test purposes
    • absmax — absolute maximun value farthest away from zero
    • median — median (middle value); more robust than mean, not influenced by outliers
    • default min
  • ptpengine:delay_stat_filter_window [INT: 3 .. 128] — number of samples used for the Delay statistical filter. default 4 🌈
  • ptpengine:delay_stat_filter_window_type [SELECT] — sampling window behaviour for the Delay statistical filter:
    • options: sliding interval
    • sliding — sliding window; a value is output every time the filter runs, which can result in duplicates
    • interval — only output a value every n-th sample (full window); independent sampling periods
    • default sliding
  • ptpengine:delay_outlier_filter_enable [BOOLEAN] — enables the outlier filter for the Delay Response component, but only in slave state. default N 🦋
  • ptpengine:delay_outlier_filter_action [SELECT] — what we do with Delay Response outliers:
    • options: discard filter
    • if set to filter, outliers are replaced with moving average 🫶
    • default discard
  • ptpengine:delay_outlier_filter_capacity [INT: 4 .. 60] — number of samples in the Delay Response outlier filter buffer. default 20
  • ptpengine:delay_outlier_filter_threshold [FLOAT: 0.001000 .. 1000.000000] — Delay Response outlier filter threshold: the multiplier for Peirce's maximum standard deviation. set it below 1.0 and the filter is tighter, set it above 1.0 and the filter is looser than the standard Peirce's test. default 1.000000 ⭐
  • ptpengine:delay_outlier_filter_always_filter [BOOLEAN] — always run the Delay Response outlier filter, even if the clock is being slewed at maximum rate. default N
  • ptpengine:delay_outlier_filter_autotune_enable [BOOLEAN] — enables automatic threshold control for the Delay Response outlier filter. default Y (yes bestie, this one's on by default 💖)
  • ptpengine:delay_outlier_filter_autotune_minpercent [INT: 0 .. 99] — Delay Response outlier filter autotune low watermark: the minimum percentage of discarded samples in the update period before the filter gets tightened by the autotune step value. default 20
  • ptpengine:delay_outlier_filter_autotune_maxpercent [INT: 1 .. 100] — Delay Response outlier filter autotune high watermark: the maximum percentage of discarded samples in the update period before the filter gets loosened by the autotune step value. default 95
  • ptpengine:delay_outlier_filter_autotune_step [FLOAT: 0.010000 .. 10.000000] — the value the Delay Response outlier filter threshold is increased or decreased by when auto-tuning. default 0.100000
  • ptpengine:delay_outlier_filter_autotune_minthreshold [FLOAT: 0.010000 .. 10.000000] — minimum Delay Response filter threshold value used when auto-tuning. default 0.100000
  • ptpengine:delay_outlier_filter_autotune_maxthreshold [FLOAT: 0.010000 .. 10.000000] — maximum Delay Response filter threshold value used when auto-tuning. default 5.000000
  • ptpengine:delay_outlier_weight [FLOAT: 0.010000 .. 2.000000] — Delay Response outlier weight: if an outlier is detected, this decides the amount of its deviation from mean that's used to build the standard deviation statistics and influence further outlier detection. when set to 1.0, the outlier is used as is. default 1.000000
  • ptpengine:delay_outlier_filter_stepdetect_enable [BOOLEAN] — enables Delay Response filter step detection (delaySM) to block when a certain level is exceeded. default N 🙈
  • ptpengine:delay_outlier_filter_stepdetect_threshold [INT: 50000 .. 999999999] — Delay step detection threshold. step detection is only performed when delaySM is below this threshold (nanoseconds). default 1000000
  • ptpengine:delay_outlier_filter_stepdetect_level [INT: 50000 .. 999999999] — Delay step level. when step detection is enabled and operational, delaySM above this level (nanoseconds) is considered a clock step and updates are paused. default 500000
  • ptpengine:delay_outlier_filter_stepdetect_credit [INT: 50 .. 1000] — initial credit (number of samples) the Delay step detection filter can block for. when credit is exhausted, the filter stops blocking. credit is gradually restored (see ptpengine:delay_outlier_filter_stepdetect_credit_increment). default 200
  • ptpengine:delay_outlier_filter_stepdetect_credit_increment [INT: 1 .. 100] — amount of credit for the Delay step detection filter restored every full sample window. default 10
  • ptpengine:sync_outlier_filter_enable [BOOLEAN] — enables the outlier filter for the Sync component, in slave state. default N 👑
  • ptpengine:sync_outlier_filter_action [SELECT] — what happens to Sync outliers:
    • options: discard filter
    • if set to filter, outliers are replaced with moving average 🌸
    • default discard
  • ptpengine:sync_outlier_filter_capacity [INT: 4 .. 60] — number of samples in the Sync outlier filter buffer. default 20
  • ptpengine:sync_outlier_filter_threshold [FLOAT: 0.001000 .. 1000.000000] — Sync outlier filter threshold: multiplier for the Peirce's maximum standard deviation. below 1.0 = tighter filter, above 1.0 = looser than the standard Peirce's test. default 1.000000 ✨
  • ptpengine:sync_outlier_filter_always_filter [BOOLEAN] — always run the Sync outlier filter, even if the clock is being slewed at maximum rate. default N
  • ptpengine:sync_outlier_filter_autotune_enable [BOOLEAN] — enables automatic threshold control for the Sync outlier filter. default Y 💖
  • ptpengine:sync_outlier_filter_autotune_minpercent [INT: 0 .. 99] — Sync outlier filter autotune low watermark: minimum percentage of discarded samples in the update period before the filter is tightened by the autotune step value. default 20
  • ptpengine:sync_outlier_filter_autotune_maxpercent [INT: 1 .. 100] — Sync outlier filter autotune high watermark: maximum percentage of discarded samples in the update period before the filter is loosened by the autotune step value. default 95
  • ptpengine:sync_outlier_filter_autotune_step [FLOAT: 0.010000 .. 10.000000] — the value the Sync outlier filter threshold is increased or decreased by when auto-tuning. default 0.100000
  • ptpengine:sync_outlier_filter_autotune_minthreshold [FLOAT: 0.010000 .. 10.000000] — minimum Sync filter threshold value used when auto-tuning. default 0.100000
  • ptpengine:sync_outlier_filter_autotune_maxthreshold [FLOAT: 0.010000 .. 10.000000] — … 🧚

Wrapping up that filter-threshold entry: usage — Maximum Sync filter threshold value used when auto-tuning; default — 5.000000.

  • ptpengine:sync_outlier_weight [FLOAT: 0.010000 .. 2.000000] — bestie, this is the outlier weight: if an outlier is detected, this value determines the amount of its deviation from mean that is used to build the standard deviation statistics and influence further outlier detection. When set to 1.0, the outlier is used as is.
    • default: 1.000000
  • ptpengine:sync_outlier_filter_stepdetect_enable [BOOLEAN] — Enable Sync filter step detection (delayMS) to block when certain level exceeded.
    • default: N
  • ptpengine:sync_outlier_filter_stepdetect_threshold [INT: 50000 .. 999999999] — Sync step detection threshold. Step detection is performed only when delayMS is below this threshold (nanoseconds).
    • default: 1000000
  • ptpengine:sync_outlier_filter_stepdetect_level [INT: 50000 .. 999999999] — Sync step level. When step detection enabled and operational, delayMS above this level (nanoseconds) is considered a clock step and updates are paused.
    • default: 500000
  • ptpengine:sync_outlier_filter_stepdetect_credit [INT: 50 .. 1000] — Initial credit (number of samples) the Sync step detection filter can block for. When credit is exhausted, filter stops blocking. Credit is gradually restored (see ptpengine:sync_outlier_filter_stepdetect_credit_increment).
    • default: 200
  • ptpengine:sync_outlier_filter_stepdetect_credit_increment [INT: 1 .. 100] — Amount of credit for the Sync step detection filter restored every full sample window.
    • default: 10
  • ptpengine:sync_sequence_checking [BOOLEAN] — When enabled, Sync messages will only be accepted if sequence ID is increasing. note: This can cause the slave to temporarily lock up if GM restarts before announce timeout, so this is limited to 50 consecutive sequence errors. Alternatively, ptpengine:clock_update_timeout can be used to reset the slave beforehand.
    • default: N
  • ptpengine:clock_update_timeout [INT: 0 .. 3600] — If set to non-zero, time (seconds) before slave is reset back into PTP_LISTENING, if there were no clock updates. This is useful for situations where slave is in SLAVE state (receiving Announce) but is not receiving or not accepting Sync messages.
    • default: 0
  • ptpengine:calibration_delay [INT: 0 .. 300] — Delay between moving to slave state and enabling clock updates (seconds). This allows mean path delay to stabilise before starting clock updates. Activated when going into slave state and during slave's GM failover. 0 - not used.
    • default: 0
  • ptpengine:idle_timeout [INT: 10 .. 3600] — PTP idle timeout (seconds): if PTPd is in SLAVE state and there have been no clock updates for this amount of time, PTPd releases clock control.
    • default: 0
  • ptpengine:panic_mode [BOOLEAN] — Enable panic mode: when offset from master is above 1 second, stop updating the clock for a period of time and then step the clock if offset remains above 1 second.
    • default: N
  • ptpengine:panic_mode_duration [INT: 1 .. 60] — Duration (minutes) of the panic mode period (no clock updates) when offset above 1 second detected.
    • default: 2
  • ptpengine:panic_mode_release_clock [BOOLEAN] — When entering panic mode, release clock control while panic mode lasts. If not set, PTP will hold clock control during panic mode. If set together with ntpengine:* configured, this will fail over to NTP.
    • default: N
  • ptpengine:panic_mode_exit_threshold [INT: 0 .. 999999999] — Do not exit panic mode until offset drops below this value (nanoseconds). 0 = not used.
    • default: 0
  • ptpengine:pid_as_clock_identity [BOOLEAN] — Use PTPd's process ID as the middle part of the PTP clock ID - useful for running multiple instances.
    • default: N
  • ptpengine:ntp_failover [BOOLEAN] — Fail over to NTP when PTP time sync not available - requires ntpengine:enabled, but does not require the rest of NTP configuration: will warn instead of failing over if cannot control ntpd.
    • default: N
  • ptpengine:ntp_failover_timeout [INT: 0 .. 1800] — NTP failover timeout in seconds: time between PTP slave going into LISTENING state, and failing over to NTP. 0 = fail over immediately. This setting controls the time provider election hold time.
    • default: 60
  • ptpengine:prefer_ntp [BOOLEAN] — Prefer NTP time synchronisation. Only use PTP when NTP not available. Could be used when NTP runs with a local GPS receiver or another hardware reference.
    • default: N
  • ptpengine:panic_mode_ntp [BOOLEAN] — Deprecated as of 2.3.1, but still supported: see ptppengine:panic_mode_release_clock.
    • default: N
  • ptpengine:sigusr2_clears_counters [BOOLEAN] — Clear counters after dumping all counter values on SIGUSR2.
    • default: N
  • ptpengine:timing_acl_permit [STRING] — Permit access control list for timing and signaling messages. Format is a series of network prefixes and/or IP addresses separated by commas, spaces, tabs or semicolons. Accepted format is CIDR notation (a.b.c.d/mm), single IP address (a.b.c.d), or full network/mask (a.b.c.d/m.m.m.m). Shortcuts can be used: 172.16/12 is expanded to 172.16.0.0/12; 192.168/255.255 is expanded to 192.168.0.0/255.255.0.0, etc. The match is performed on the source IP address of the incoming messages. IP access lists are only supported when using the IP transport.
    • default: [none]
  • ptpengine:timing_acl_deny [STRING] — Deny access control list for timing and signaling messages. Format is a series of network prefixes and/or IP addresses separated by commas, spaces, tabs or semicolons. Accepted format is CIDR notation (a.b.c.d/mm), single IP address (a.b.c.d), or full network/mask (a.b.c.d/m.m.m.m). Shortcuts can be used: 172.16/12 is expanded to 172.16.0.0/12; 192.168/255.255 is expanded to 192.168.0.0/255.255.0.0, etc. The match is performed on the source IP address of the incoming messages. IP access lists are only supported when using the IP transport.
    • default: [none]
  • ptpengine:management_acl_permit [STRING] — Permit access control list for management messages. Format is a series of network prefixes and/or IP addresses separated by commas, spaces, tabs or semicolons. Accepted format is CIDR notation (a.b.c.d/mm), single IP address (a.b.c.d), or full network/mask (a.b.c.d/m.m.m.m). Shortcuts can be used: 172.16/12 is expanded to 172.16.0.0/12; 192.168/255.255 is expanded to 192.168.0.0/255.255.0.0, etc. The match is performed on the source IP address of the incoming messages. IP access lists are only supported when using the IP transport.
    • default: [none]
  • ptpengine:management_acl_deny [STRING] — Deny access control list for management messages. Format is a series of network prefixes and/or IP addresses separated by commas, spaces, tabs or semicolons. Accepted format is CIDR notation (a.b.c.d/mm), single IP address (a.b.c.d), or full network/mask (a.b.c.d/m.m.m.m). Shortcuts can be used: 172.16/12 is expanded to 172.16.0.0/12; 192.168/255.255 is expanded to 192.168.0.0/255.255.0.0, etc. The match is performed on the source IP address of the incoming messages. IP access lists are only supported when using the IP transport.
    • default: [none]
  • ptpengine:timing_acl_order [SELECT]
  • ptpengine:management_acl_order [SELECT]
  • clock:no_adjust [BOOLEAN] — Do not adjust the clock.
    • default: N
  • clock:no_reset [BOOLEAN] — Do not reset the clock - only slew.
    • default: N
  • clock:step_startup_force [BOOLEAN] — Force clock step on first sync after startup regardless of offset and clock:no_reset.
    • default: N
  • clock:step_startup [BOOLEAN] — Step clock on startup only if offset >= 1 second, ignoring panic mode and clock:no_reset.
    • default: N
  • clock:set_rtc_on_step [BOOLEAN]

usage — attempt to set the RTC any time the clock gets stepped (Linux only, mwah 💋 — FreeBSD already does this for us).

⚠️ WARNING: this will always set the RTC to the OS clock time, no matter what time zones are doing, so it assumes the RTC runs in UTC or otherwise on the same timescale as PTP. True at least on most single-boot x86 Linux systems, iykyk.
  • default — N

clock:drift_handling [SELECT]

  • options — reset, preserve, file
  • usage — the method for handling observed drift between servo restarts, bestie:
    • reset — set it to zero (not recommended 🚩)
    • preserve — use the kernel value
    • file — load/save to the drift file on startup/shutdown, and use the kernel value in between. To specify the drift file, use the clock:drift_file setting.
  • default — preserve

clock:drift_file [STRING]

  • usage — specifies the drift file 🗂️
  • default — /etc/ptpd2_kernelclock.drift

clock:leap_seconds_file [STRING]

  • usage — specifies where the leap second file lives (an up-to-date version can be downloaded from http://www.ietf.org/timezones/data/leap-seconds.list ✨). When it's configured, the PTP master uses data from this file to announce leap flags and the UTC offset, overriding the OS info, and the PTP slave uses data from this file plus the info the GM supplies. If it's configured, this file is always reloaded on configuration reload (SIGHUP), reloaded on clock step, and reloaded after a leap second event, so the info stays up to date, fr fr. As of ptpd 2.3.1 the file is bundled with ptpd and gets installed into (prefix)/share/ptpd/leap-seconds.list.ddMMMyyyy, where ddMMMyyyy is the leap seconds file expiry date 🗓️
  • default — [none]

clock:leap_second_pause_period [INT: 5 .. 600]

  • usage — the time (in seconds) before and after midnight during which clock updates get suspended while a leap second event is happening. The total pause is twice whatever you configure here. Clock updates are suspended when a leap second event is pending and the time to midnight is less than or equal to this value, and they resume no earlier than this value after midnight ⏸️. They come back in a controlled way — after a control message, like a PTP announce. That's what makes sure the updated UTC offset is received before any more clock updates happen, no cap.
  • default — 5

clock:leap_second_notice_period [INT: 3600 .. 86400]

  • usage — how many seconds before midnight PTPd starts announcing the leap second when it's running as master 📣. The IEEE 1588 standard suggests 12 hours notice and that's the default, but you can change it for more flexibility.
  • default — 43200

clock:leap_second_handling [SELECT]

  • options — accept, ignore, step, smear
  • usage — clock sync behaviour during leap second events:
    • accept — inform the OS kernel about the leap second and let the kernel insert or delete it
    • ignore — don't inform the kernel — this ends up with a +/-1-second offset which then gets slewed back down
    • step — don't inform the kernel, and step the clock immediately after the leap second event
    • smear — gradually introduce an extra offset over a period of time before the leap second event, which accumulates to +/-1 second (see clock:leap_second_smear_period). Once the clock stabilises, this results in a clock frequency shift which gets taken off after the event. Once the leap second event is over, the extra offset is also removed and time is back in line with master time 👑
  • default — accept

clock:leap_second_smear_period [INT: 3600 .. 86400]

  • usage — when clock:leap_second_handling is set to smear, this setting defines the period (in seconds) before the leap second event over which the leap second offset is gradually added. Example: when set to 24 hours (86400), an extra +/-11.5 microseconds is added every second (that's an 11.5 ppm clock frequency offset) 🧚
  • default — 86400

clock:max_offset_ppm [INT: 500 .. 1000]

  • usage — the maximum absolute frequency shift that can be applied to the clock servo when slewing the clock, expressed in parts per million (1 ppm = a shift of 1 us per second). Values above 512 will use the tick duration correction to allow even faster slewing. Default maximum is 512 without using tick.
  • default — 500

servo:delayfilter_stiffness [INT]

  • usage — Mean Path Delay filter stiffness.
  • default — 6

servo:kp [FLOAT: min: 0.000001 ]

  • usage — clock servo PI controller proportional component gain (kP).
  • default — 0.100000

servo:ki [FLOAT: min: 0.000001 ]

  • usage — clock servo PI controller integral component gain (kI).
  • default — 0.001000

servo:dt_method [SELECT]

  • options — none, constant, measured
  • usage — how the servo update interval (delta t) gets calculated:
    • none — servo not corrected for update interval (dt always 1)
    • constant — a constant value (the target servo update rate) — the sync interval for PTP
    • measured — the servo measures how often it's updated and uses this interval
  • default — constant

servo:dt_max [FLOAT: 1.500000 .. 100.000000]

  • usage — maximum servo update interval (delta t) when using the measured servo update interval (servo:dt_method = measured), specified as a sync interval multiplier.
  • default — 5.000000

servo:stability_detection [BOOLEAN]

  • usage — enables clock synchronisation servo stability detection (based on the standard deviation of the observed drift value) 🦋 — drift gets saved to the drift file / cached when it's considered stable, and clock stability status gets logged too.
  • default — N

servo:stability_threshold [FLOAT: 1.000000 .. 10000.000000]

  • usage — specifies the observed drift standard deviation threshold in parts per billion (ppb) — if the standard deviation is within the threshold, the servo is considered stable ✨
  • default — 5.000000

servo:stability_period [INT: 1 .. 100]

  • usage — specifies for how many statistics update intervals the observed drift standard deviation has to stay within the threshold to be considered stable.
  • default — 3

servo:stability_timeout [INT: 1 .. 60]

  • usage — specifies after how many minutes without stabilisation the servo is considered unstable. Helps with logging servo stability info, and lets you preserve observed drift if the servo can't stabilise 😭
  • default — 10

servo:max_delay [INT: 0 .. 999999999]

  • usage — don't accept master to slave delay (delayMS — from the Sync message) or slave to master delay (delaySM — from the Delay Response message) if it's greater than this value (nanoseconds). 0 = not used.
  • default — 0

servo:max_delay_max_rejected [INT: min: 0 ]

  • usage — the maximum number of consecutive rejected delay measurements exceeding the maxDelay threshold (servo:max_delay) before the slave gets reset. 0 = not checked.
  • default — 0

servo:max_delay_stable_only [BOOLEAN]

  • usage — if servo:max_delay is set, perform the check only if the clock servo has stabilised.
  • default — N

servo:max_offset [INT: 0 .. 999999999]

  • usage — don't reset the clock if the offset from master is greater than this value (nanoseconds). 0 = not used.
  • default — 0

global:enable_snmp [BOOLEAN]

  • usage — enable the SNMP agent (if compiled with PTPD_SNMP).
  • default — N

global:use_syslog [BOOLEAN]

  • usage — send log messages to syslog. Disabling this sends all messages to stdout (or to the specified log file) 🫶
  • default — N

global:lock_file [STRING]

  • usage — lock file location.
  • default — [none]

global:auto_lockfile [BOOLEAN]

  • usage — use a mode-specific and interface-specific lock file (this overrides global:lock_file).
  • default — N

global:lock_directory [STRING]

  • usage — lock file directory: used with automatic mode-specific lock files, and also used when no lock file is specified. When a lock file is specified, it's expected to be an absolute path.
  • default — /var/run

global:ignore_lock [BOOLEAN]

  • usage — skip lock file checking and locking entirely.
  • default — N

global:quality_file [STRING]

  • usage — the file used to record data about sync packets. Recording is enabled whenever this is set 🍓
  • default — [none]

global:quality_file_max_size [INT: min: 0 ]

  • usage — maximum sync packet record file size (in kB) — the file gets truncated if the size exceeds the limit. 0 = no limit.
  • default — 0

global:quality_file_max_files [INT: 0 .. 100]

  • usage — enable log rotation of the sync packet record file up to n files. 0 = do not rotate.
  • default — 0

global:quality_file_truncate [BOOLEAN]

(stick around, bestie — this one's deets drop in the next bit 💅)

okay bestie, last little crumb of that sync packet record file truncate setting before we move on — don’t worry, we’re still slaying 💅

  • usage — Truncate the sync packet record file every time it is (re) opened: startup and SIGHUP. default: N.

now the status/log era begins, and honestly? it’s giving observability 👑

  • global:status_file [STRING] — usage: File used to log ptpd2 status information. default: /var/run/ptpd2.status
  • global:log_status [BOOLEAN] — usage: Enable / disable writing status information to file. default: N
  • global:status_update_interval [INT: 1 .. 30] — usage: Status file update interval in seconds. default: 1
  • global:log_file [STRING] — usage: Specify log file path (event log). Setting this enables logging to file. default: [none]
  • global:log_file_max_size [INT: min: 0 ] — usage: Maximum log file size (in kB) - log file will be truncated if size exceeds the limit. 0 - no limit. default: 0
  • global:log_file_max_files [INT: 0 .. 100] — usage: Enable log rotation of the sync packet record file up to n files. 0 - do not rotate. default: 0
  • global:log_file_truncate [BOOLEAN] — usage: Truncate the log file every time it is (re) opened: startup and SIGHUP. default: N
  • global:log_level [SELECT] — usage: Specify log level (only messages at this priority or higer will be logged). The minimal level is LOG_ERR. LOG_ALL enables debug output if compiled with RUNTIME_DEBUG. options: LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_ALL. default: LOG_ALL
  • global:statistics_file [STRING] — usage: Specify statistics log file path. Setting this enables logging of statistics, but can be overriden with global:log_statistics. default: [none]
  • global:statistics_log_interval [INT: min: 0 ] — usage: Log timing statistics every n seconds for Sync and Delay messages (0 - log all). default: 0
  • global:statistics_file_max_size [INT: min: 0 ] — usage: Maximum statistics log file size (in kB) - log file will be truncated if size exceeds the limit. 0 - no limit. default: 0
  • global:statistics_file_max_files [INT: 0 .. 100] — usage: Enable log rotation of the statistics file up to n files. 0 - do not rotate. default: 0
  • global:statistics_file_truncate [BOOLEAN] — usage: Truncate the statistics file every time it is (re) opened: startup and SIGHUP. default: N
  • global:dump_packets [BOOLEAN] — usage: Dump the contents of every PTP packet. default: N
  • global:verbose_foreground [BOOLEAN] — usage: Run in foreground with statistics and all messages logged to stdout. Overrides log file and statistics file settings and disables syslog. default: N
  • global:foreground [BOOLEAN] — usage: Run in foreground - ignored when global:verbose_foreground is set. default: N
  • global:log_statistics [BOOLEAN] — usage: Log timing statistics for every PTP packet received. Output is in CSV format and field headers are always printed when starting or refreshing the statistics log. default: N
  • global:statistics_timestamp_format [SELECT] — usage: Timestamp format used when logging timing statistics (when global:log_statistics is enabled):
    • datetime — Formatted date and time: YYYY-MM-DD hh:mm:ss.uuuuuu
    • unix — Unix timestamp with nanoseconds: s.ns
    • both — Formatted date and time followed by unix timestamp (adds one extra field to the log) options: datetime, unix, both. default: datetime
  • global:periodic_updates [BOOLEAN] — usage: Log a status update every time statistics are updated (global:statistics_update_interval). This update is written to the main log target. Status updates are logged even if ptpd is configured without support for statistics. default: N
  • global:cpuaffinity_cpucore [INT: -1 .. 255] — usage: Bind ptpd2 process to a selected CPU core number. 0 = first CPU core, etc. -1 = do not bind to a single core. default: 0
  • global:statistics_update_interval [INT: 1 .. 60] — usage: Clock synchronisation statistics update interval in seconds. Also controls how often periodic status information is logged (when using global:statistics_update_interval). default: 30
  • global:timingdomain_election_delay [INT: 0 .. 3600 ] — usage: Delay (seconds) before releasing a time service (NTP or PTP) and electing a new one to control a clock. 0 = elect immediately. default: 15
  • ntpengine:enabled [BOOLEAN] — usage: Enable NTPd integration. default: N
  • ntpengine:control_enabled [BOOLEAN] — usage: Enable control over local NTPd daemon. default: N
  • ntpengine:check_interval [INT: 5 .. 600] — usage: NTP control check interval in seconds. default: 15
  • ntpengine:key_id [INT: 0 .. 65535] — usage: NTP key number - must be configured as a trusted control key in ntp.conf, and be non-zero for the ntpengine:control_enabled setting to take effect. default: 0
  • ntpengine:key [STRING] — usage: NTP key (plain text, max. 20 characters) - must match the key configured in ntpd's keys file, and must be non-zero for the ntpengine:control_enabled setting to take effect. default: [none]

💀 BUGS 💀

okay so real talk: configuration file support has only been introduced in version 2.3. There may still be some inconsistencies in the way some settings are parsed, and while order should not make any difference, for some complex behaviours it may still be the case. 🙈

Please report any bugs using the bug tracker on the SourceForge page: http://sourceforge.net/projects/ptpd/

👀 SEE ALSO 👀

  • ptpd2(8) — yes bestie, go read the big one too 💅

👑 AUTHORS 👑

  • Steven Kreuzer <skreuzer@freebsd.org>
  • Gael Mace <gael_mace@users.sourceforge.net>
  • George Neville-Neil <gnn@freebsd.org>
  • Wojciech Owczarek <wojciech@owczarek.co.uk>
  • Alexandre Van Kempen

ptpd2.conf(5) man page first written by Wojciech Owczarek for ptpd 2.3.0 in November 2013

and that’s the whole page, bestie 🎀 this beauty is from version 2.3.1, dated June, 2015, and it’s the ptpd2.conf(5) page. periodt. 💖

📦 where this page comes from