ptpd2.conf(5)

📦 version 2.3.1-debian1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ ptpd2.conf(5) ✨

okay so bestie, this is the manual for ptpd2.conf — the config file for the PTPd daemon 💖 (PTPd = Precision Time Protocol daemon, no cap). Everything you could ever want to tweak lives in here, and I'm about to walk you through it like we're gossiping at lunch. Buckle up 🎀

🌸 NAME 🌸

ptpd2.conf — Precision Time Protocol daemon config file. That's it, that's the girl 💅

📝 CONFIGURATION FILE FORMAT 📝

Settings in the PTPd config file are grouped into sections, and they take the form of section:key="value" variables. You've got two ways to write it:

  • the section:key="value" way (this is the preferred one, do this one bestie 🫶)
  • or .ini file style, where you have a bunch of key="value" variables grouped into sections using [section] headers

Every single setting listed in here can ALSO be passed as a command line parameter, like --section:key=value. Quotation marks are optional (so unserious of them, but okay ✨).

NOTE: the configuration file must end with a newline. That's the whole rule. Don't forget it or she will simply not vibe with you 😭

🔄 RELOADING CONFIGURATION 🔄

Only a small number of config file settings require a restart of the PTPd process to take effect — specifically the SNMP and lock file configuration ones. Everybody else? They can be changed while ptpd is running, because the config file gets reloaded and checked for changes whenever PTPd receives the SIGHUP signal. iconic behaviour honestly 💖

When reloading config, PTPd will always attempt to test the 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 — and a warning gets logged every single time you try to change them through the config file. She's not mad, she's just disappointed 🙈

🗂️ 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 ⭐

ptpengine

  • 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, slave will keep alternating between primary and secondary until a GM is found. (GM = grandmaster, she's the main character of the clock world 👑)
    • 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 (the transportSpecific field in PTP message headers). Requires Ethernet transport, since that's 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 the masteronly preset — all Announce messages will be ignored and the clock 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 the 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 the 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 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 the UTC offset announced by the best master, even if 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 the BMC algorithm: when enabled, BMC for both master and slave 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 up right where that last one left off 💫 the usage goes like this: when an announce receipt timeout happens while you're in slave state, you disqualify the current best GM, then wait n times the announce receipt timeout before you reset. It's giving seamless GM failover when your standby GMs are slow to react 🐌. Set it to 0 and bestie, this option is simply not used 💅

  • default: 0
  • ptpengine:log_sync_interval [INT: -7 .. 7] — the PTP sync message interval when you're in master state. When you're running unicast negotiation (ptpengine:unicast_negotiation), for slaves this is the initial (minimum) interval requested, and for masters it's the minimum interval granted. (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 (ptpengine:unicast_negotiation) is on, this is the maximum sync interval a master will grant, and the maximum interval a slave will even attempt to request. (expressed as log 2 i.e. -1=0.5s, 0=1s, 1=2s etc.)
    • default: 5
  • ptpengine:log_delayreq_override [BOOLEAN] — override the Delay Request interval that the best master handed you. Yes, you can just do that 👑
    • default: N
  • ptpengine:log_delayreq_auto [BOOLEAN] — automatically override the Delay Request interval (using ptpengine:log_delayreq_interval) if the value you received is 127 (0X7F), like in unicast messages — unless you're using 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. (expressed as log 2 i.e. -1=0.5s, 0=1s, 1=2s etc.)
    • default: 0
  • ptpengine:log_delayreq_interval [INT: -7 .. 7] — the minimum delay request interval announced when you're in master state; in slave state it overrides the master's interval. (expressed as log 2 i.e. -1=0.5s, 0=1s, 1=2s etc.). When unicast negotiation (ptpengine:unicast_negotiation) is on: for slaves this is the initial (minimum) interval requested, and for masters it's 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 interval a slave will attempt to request. (expressed as log 2 i.e. -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 (expressed as log 2 i.e. -1=0.5s, 0=1s, 1=2s etc.). With unicast negotiation (ptpengine:unicast_negotiation) on, 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 a node grants, and the maximum interval a node will attempt to request from its peer. (expressed as log 2 i.e. -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 you're willing to keep track of 🧚
    • default: 5
  • ptpengine:ptp_allan_variance [INT: 0 .. 65535] — specify the Allan variance announced in master state 📣
    • default: 28768
  • ptpengine:ptp_clock_accuracy [SELECT] — the clock accuracy range announced in master state.
    • options: 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
  • ptpengine:utc_offset [INT] — the UTC offset of the underlying time source, announced in master state ⏰
    • default: 0
  • ptpengine:utc_offset_valid [BOOLEAN] — is that underlying time source UTC offset 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] — the underlying time source's frequency traceability, announced in master state.
    • default: N
  • ptpengine:ptp_timescale [SELECT] — the time scale announced in master state (with ARB, UTC properties get straight-up ignored by slaves 🙈). When the clock class is set to 13 (application specific), this value is ignored and ARB is used instead.
    • options: PTP ARB
    • default: ARB
  • ptpengine:ptp_timesource [SELECT] — the time source announced in master state 🌈
    • options: ATOMIC_CLOCK GPS TERRESTRIAL_RADIO PTP NTP HAND_SET OTHER INTERNAL_OSCILLATOR
    • default: INTERNAL_OSCILLATOR
  • ptpengine:clock_class [INT: 0 .. 255] — the clock class, announced in master state. Always 255 for slave-only. The minimum, maximum and default values are controlled by presets. If it's set to 13 (application specific time source), the announced time scale is always set to ARB. This setting is the one controlling which states a PTP port can be in: if it's below 128, the port will only be in MASTER or PASSIVE states (master only). If it's 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, used for Best Master Clock selection.
    • default: 128
  • ptpengine:max_listen [INT: min: 1] — how many consecutive protocol resets to LISTENING you'll allow before going full network reset 💀
    • default: 5
  • ptpengine:unicast_destinations [STRING] — an IPv4 address, or a whole list of them, 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] — specify the PTP domain number for each configured unicast destination (ptpengine:unicast_destinations). Only slave-only clocks using unicast destinations use this, so each master can live 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] — specify a local preference for each configured unicast destination (ptpengine:unicast_destinations). Again, only slave-only clocks using unicast destinations use this, so a slave can locally influence each master's BMC selection — like with Telecom Profile. The number of entries should match the number of unicast destinations, otherwise the unconfigured preference is 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) and 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] — enable handling of PTP management messages. Only GET messages get processed by default. Peep ptpengine:management_set_enable for the spicier stuff 🌶️
    • default: Y
  • ptpengine:management_set_enable [BOOLEAN] — accept SET and COMMAND management messages.
    • default: N
  • ptpengine:igmp_refresh [BOOLEAN] — send 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 (in seconds) while in master state when running IPv4 multicast. Heads up: if it's set below 10, or if ptpengine:igmp_refresh is disabled, this setting does literally nothing 🙈
    • 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] — DiffServ CodepPoint for packet prioritisation (decimal). When it's set to zero, this option is not used. Use 46 for Expedited Forwarding (0x2e) 🚀
    • default: 0
  • ptpengine:sync_stat_filter_enable [BOOLEAN] — okay bestie hold that thought, this one's got more coming 💅
  • ...and to finish off the one that got cut off right above this: its whole personality is enable the statistical filter for Sync messages, and it ships off by default (N). (Name's on the previous line bestie, we're mid-list, keep up 💅)
  • ptpengine:sync_stat_filter_type [SELECT] — the vibe check for your Sync filter: which flavour of filter is doing the filtering on Sync messages:
    • none — no filtering — pass-through, zero thoughts, just vibes
    • 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 maximum value farthest away from zero
    • median — median (middle value) — more robust than mean, not influenced by outliers
    • Default: min
  • ptpengine:sync_stat_filter_window [INT: 3 .. 128] — how many samples get to hang out in the Sync statistical filter's little friend group
    • Default: 4
  • ptpengine:sync_stat_filter_window_type [SELECT] — how the sampling window behaves for the Sync statistical filter:
    • 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_stat_filter_enable [BOOLEAN] — turn on the statistical filter for Delay messages ✨
    • Default: N
  • ptpengine:delay_stat_filter_type [SELECT] — which flavour of filter is doing the filtering on Delay messages:
    • none — no filtering — pass-through, unbothered, unproblematic
    • 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 maximum 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:
    • 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

🫶 delay outlier filter (slave state, delay response edition)

  • ptpengine:delay_outlier_filter_enable [BOOLEAN] — enable the outlier filter for the Delay Response component, but only when you're in slave state 👑
    • Default: N
  • ptpengine:delay_outlier_filter_action [SELECT] — what to do when the Delay Response outlier filter catches an outlier. If it's set to filter, the outliers are replaced with moving average 🪄
    • discard
    • filter
    • Default: discard
  • ptpengine:delay_outlier_filter_capacity [INT: 4 .. 60] — how many samples get to fit in the Delay Response outlier filter buffer 🎀
    • Default: 20
  • ptpengine:delay_outlier_filter_threshold [FLOAT: 0.001000 .. 1000.000000] — the Delay Response outlier filter threshold: a multiplier for Peirce's maximum standard deviation. Set it below 1.0 and the filter is tighter; set it above 1.0 and it's 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. No days off, no excuses 💅
    • Default: N
  • ptpengine:delay_outlier_filter_autotune_enable [BOOLEAN] — enable automatic threshold control for the Delay Response outlier filter ✨
    • Default: Y
  • 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 gets 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 gets detected, this decides the amount of its deviation from mean that's used to build the standard deviation statistics and influence further outlier detection. Set it to 1.0 and the outlier is used as-is 🦋
    • Default: 1.000000
  • ptpengine:delay_outlier_filter_stepdetect_enable [BOOLEAN] — enable Delay Response filter step detection (delaySM) so it can block when a certain level is exceeded
    • Default: N
  • ptpengine:delay_outlier_filter_stepdetect_threshold [INT: 50000 .. 999999999] — Delay step detection threshold. Step detection only happens 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, a 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] — the initial credit (number of samples) the Delay step detection filter is allowed to block for. Once the 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] — how much credit for the Delay step detection filter gets restored every full sample window
    • Default: 10

🌈 sync outlier filter (slave state, sync edition)

  • ptpengine:sync_outlier_filter_enable [BOOLEAN] — enable the outlier filter for the Sync component, in slave state 👑
    • Default: N
  • ptpengine:sync_outlier_filter_action [SELECT] — Sync outlier filter action. If it's set to filter, the outliers are replaced with moving average 🪄
    • discard
    • filter
    • 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: a 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. It's giving dedication 💅
    • Default: N
  • ptpengine:sync_outlier_filter_autotune_enable [BOOLEAN] — enable 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: the minimum percentage of discarded samples in the update period before the filter gets tightened by the autotune step value
    • Default: 20
  • ptpengine:sync_outlier_filter_autotune_maxpercent [INT: 1 .. 100] — Sync 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:sync_outlier_filter_autotune_step [FLOAT: 0.010000 .. 10.000000] — the value the Sync outlier filter threshold gets 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] —
  • usage — the maximum Sync filter threshold value used when auto-tuning ✨
    • default — 5.000000
  • ptpengine:sync_outlier_weight [FLOAT: 0.010000 .. 2.000000]
    • usage — the Sync outlier weight 🫶 if an outlier gets detected, this value decides how much of its deviation from the mean is used to build the standard deviation statistics and to influence further outlier detection. Set it to 1.0 and the outlier is used as is, no filter, no edits, periodt.
    • default — 1.000000
  • ptpengine:sync_outlier_filter_stepdetect_enable [BOOLEAN]
    • usage — turn on Sync filter step detection (delayMS) so it blocks once a certain level gets exceeded 🚧
    • default — N
  • ptpengine:sync_outlier_filter_stepdetect_threshold [INT: 50000 .. 999999999]
    • usage — the Sync step detection threshold. Step detection only even happens when delayMS is below this threshold, in nanoseconds 👀
    • default — 1000000
  • ptpengine:sync_outlier_filter_stepdetect_level [INT: 50000 .. 999999999]
    • usage — the Sync step level. When step detection is enabled and operational, a delayMS above this level (nanoseconds) counts as a clock step and updates get paused 🛑
    • default — 500000
  • ptpengine:sync_outlier_filter_stepdetect_credit [INT: 50 .. 1000]
    • usage — the initial credit (number of samples) the Sync step detection filter is allowed to block for. Once the credit is exhausted, the filter stops blocking. Credit gets gradually restored (peep ptpengine:sync_outlier_filter_stepdetect_credit_increment) 🎟️
    • default — 200
  • ptpengine:sync_outlier_filter_stepdetect_credit_increment [INT: 1 .. 100]
    • usage — how much credit the Sync step detection filter gets restored every full sample window 💫
    • default — 10
  • ptpengine:sync_sequence_checking [BOOLEAN]
    • usage — when this is on, Sync messages only get accepted if the sequence ID is increasing 📈
    • note — this can make the slave temporarily lock up if the GM restarts before the announce timeout, so it's 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]
    • usage — if you set this to non-zero, it's the time (seconds) before the slave is reset back into PTP_LISTENING when there were no clock updates. So useful for when the slave is sitting in SLAVE state (receiving Announce) but isn't receiving, or isn't accepting, Sync messages 😭
    • default — 0
  • ptpengine:calibration_delay [INT: 0 .. 300]
    • usage — the delay (seconds) between moving into slave state and enabling clock updates. This lets mean path delay stabilise before clock updates kick off. It activates when going into slave state and during the slave's GM failover. 0 means it's not used 🙅
    • default — 0
  • ptpengine:idle_timeout [INT: 10 .. 3600]
    • usage — PTP idle timeout (seconds): if PTPd is in SLAVE state and there have been no clock updates for this long, PTPd releases clock control 🕰️
    • default — 0
  • ptpengine:panic_mode [BOOLEAN]
    • usage — enable panic mode: when the offset from master is above 1 second, stop updating the clock for a period of time, and then step the clock if the offset is still above 1 second 😱
    • default — N
  • ptpengine:panic_mode_duration [INT: 1 .. 60]
    • usage — how long the panic mode period lasts, in minutes (no clock updates), once an offset above 1 second gets detected ⏳
    • default — 2
  • ptpengine:panic_mode_release_clock [BOOLEAN]
    • usage — when entering panic mode, release clock control for as long as panic mode lasts. If it's not set, PTP holds onto clock control during panic mode. If it's set together with ntpengine:* configured, this will fail over to NTP 💅
    • default — N
  • ptpengine:panic_mode_exit_threshold [INT: 0 .. 999999999]
    • usage — do not exit panic mode until the offset drops below this value (nanoseconds). 0 = not used 🚪
    • default — 0
  • ptpengine:pid_as_clock_identity [BOOLEAN]
    • usage — use PTPd's process ID as the middle part of the PTP clock ID — iconic for running multiple instances 👯
    • default — N
  • ptpengine:ntp_failover [BOOLEAN]
    • usage — fail over to NTP when PTP time sync isn't available. It requires ntpengine:enabled, but it does not require the rest of the NTP configuration: if it can't control ntpd it'll warn instead of failing over 🚨
    • default — N
  • ptpengine:ntp_failover_timeout [INT: 0 .. 1800]
    • usage — the NTP failover timeout in seconds: the time between the 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]
    • usage — prefer NTP time synchronisation. Only use PTP when NTP isn't available. Could be used when NTP runs with a local GPS receiver or another hardware reference 🛰️
    • default — N
  • ptpengine:panic_mode_ntp [BOOLEAN]
    • usage — deprecated as of 2.3.1, but still supported: see ptppengine:panic_mode_release_clock. (yes bestie, that's spelled with two p's, I'm not touching it 🙈)
    • default — N
  • ptpengine:sigusr2_clears_counters [BOOLEAN]
    • usage — clear the counters after dumping all their values on SIGUSR2 🧹
    • default — N
  • ptpengine:timing_acl_permit [STRING]
    • usage — the 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 formats are CIDR notation (a.b.c.d/mm), a single IP address (a.b.c.d), or a full network/mask (a.b.c.d/m.m.m.m). Shortcuts work too: 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]
    • usage — the 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 formats are CIDR notation (a.b.c.d/mm), a single IP address (a.b.c.d), or a full network/mask (a.b.c.d/m.m.m.m). Shortcuts work too: 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]
    • usage — the 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 formats are CIDR notation (a.b.c.d/mm), a single IP address (a.b.c.d), or a full network/mask (a.b.c.d/m.m.m.m). Shortcuts work too: 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]
    • usage — the 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 formats are CIDR notation (a.b.c.d/mm), a single IP address (a.b.c.d), or a full network/mask (a.b.c.d/m.m.m.m). Shortcuts work too: 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]

okay bestie, vibe shift 💫 we're out of the engine tuning and into the clock options — these are the ones that decide whether PTPd is even allowed to touch your system time. buckle up 🎀

  • clock:no_adjust [BOOLEAN]
    • usage — do not adjust the clock 🙅‍♀️
    • default — N
  • clock:no_reset [BOOLEAN]
    • usage — do not reset the clock — only slew 🌊
    • default — N
  • clock:step_startup_force [BOOLEAN]
    • usage — force a clock step on the first sync after startup, regardless of offset and regardless of clock:no_reset 💥
    • default — N
  • clock:step_startup [BOOLEAN]
    • usage — step the clock on startup only if the offset is >= 1 second, ignoring panic mode and clock:no_reset 💥
    • default — N
  • clock:set_rtc_on_step [BOOLEAN]
  • clock:set_rtc — Attempt setting the RTC when stepping the clock. (Linux only — FreeBSD does this for us, bestie 💅)
⚠️ WARNING: this will always set the RTC to OS clock time, regardless of time zones, so this assumes that RTC runs in UTC or otherwise in the same timescale as PTP. True at least on most single-boot x86 Linux systems. So like, be careful, okay? 😭

Default: N

  • clock:drift_handling — SELECT. Observed drift handling method between servo restarts. Your choices are:
    • reset — set to zero (not recommended, bestie, don't do it) 🙅‍♀️
    • preserve — use kernel value
    • file — load/save to drift file on startup/shutdown, use kernel value inbetween. To specify drift file, use the clock:drift_file setting.

Default: preserve

  • clock:drift_file — STRING. Specify drift file. Just point me to the file, bestie 📁

Default: /etc/ptpd2_kernelclock.drift

  • clock:leap_seconds_file — STRING. Specify leap second file location. (up to date version can be downloaded from: http://www.ietf.org/timezones/data/leap-seconds.list). When configured, PTP master will use data from this file to announce leap flags and UTC offset, overriding OS information, and PTP slave will use data from this file as well as information supplied by the GM. If configured, this file is always reloaded on configuration reload (SIGHUP), reloaded on clock step and reloaded after a leap second event to ensure the information is up to date. As of ptpd 2.3.1, the file is bundled with ptpd and is installed into (prefix)/share/ptpd/leap-seconds.list.ddMMMyyyy where ddMMMyyyy is the leap seconds file expiry date. Iconic.

Default: [none]

  • clock:leap_second_pause_period — INT: 5 .. 600. Time (seconds) before and after midnight that clock updates should be suspended for during a leap second event. The total duration of the pause is twice the configured duration. Clock updates are suspended when there is a leap second event pending and time to midnight is less than or equal to this value and resumed no earlier than this value after midnight. Clock updates are resumed in a controlled manner — after a control message, such as PTP announce. This ensures that the updated UTC offset is received before any further clock updates. So like, we pause, we vibe, we resume properly. Periodt.

Default: 5

  • clock:leap_second_notice_period — INT: 3600 .. 86400. Time (seconds) before midnight that PTPd starts announcing the leap second if it's running as master. The IEEE 1588 standard suggests 12 hours notice and this is the default, but it may be changed to allow more flexibility. 12 hours notice? That's like, so much notice, but okay 👑

Default: 43200

  • clock:leap_second_handling — SELECT. Clock sync behaviour during leap second events. Your options are:
    • accept — Inform OS kernel about the leap second and let the kernel insert or delete the leap second.
    • ignore — Do not inform the kernel — this ends with a +/-1-second offset which is then slewed back down.
    • step — Do not 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 is 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. Smear is giving smooth operator energy ✨

Default: accept

  • clock:leap_second_smear_period — INT: 3600 .. 86400. 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 (11.5 ppm clock frequency offset). Math is mathing, bestie 🧮

Default: 86400

  • clock:max_offset_ppm — INT: 500 .. 1000. Maximum absolute frequency shift which can be applied to the clock servo when slewing the clock. Expressed in parts per million (1 ppm = 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. So like, don't go over 512 unless you know what you're doing, okay? 💅

Default: 500

  • servo:delayfilter_stiffness — INT. Mean Path Delay filter stiffness. Stiffness, but make it delay filter 💜

Default: 6

  • servo:kp — FLOAT: min: 0.000001. Clock servo PI controller proportional component gain (kP). PI controller? More like pie controller, because it's sweet 🥧

Default: 0.100000

  • servo:ki — FLOAT: min: 0.000001. Clock servo PI controller integral component gain (kI). And here's the integral part, bestie 💖

Default: 0.001000

  • servo:dt_method — SELECT. How servo update interval (delta t) is calculated. Your choices:
    • none — servo not corrected for update interval (dt always 1),
    • constant — constant value (target servo update rate) — sync interval for PTP,
    • measured — servo measures how often it's updated and uses this interval.

Default: constant

  • servo:dt_max — FLOAT: 1.500000 .. 100.000000. Maximum servo update interval (delta t) when using measured servo update interval (servo:dt_method = measured), specified as sync interval multiplier. So like, the max delta t, but make it a multiplier 🌈

Default: 5.000000

  • servo:stability_detection — BOOLEAN. Enable clock synchronisation servo stability detection (based on standard deviation of the observed drift value) — drift will be saved to drift file / cached when considered stable, also clock stability status will be logged. Stability check! We love a stable queen 👑

Default: N

  • servo:stability_threshold — FLOAT: 1.000000 .. 10000.000000. Specify the observed drift standard deviation threshold in parts per billion (ppb) — if standard deviation is within the threshold, servo is considered stable. So like, if the std dev is under this, we're stable, periodt.

Default: 5.000000

  • servo:stability_period — INT: 1 .. 100. Specify for how many statistics update intervals the observed drift standard deviation has to stay within threshold to be considered stable. How many intervals? Like, how many times do we need to see it be stable? This many.

Default: 3

  • servo:stability_timeout — INT: 1 .. 60. Specify after how many minutes without stabilisation servo is considered unstable. Assists with logging servo stability information and allows one to preserve observed drift if servo cannot stabilise. If it takes too long, we call it unstable. No cap.

Default: 10

  • servo:max_delay — INT: 0 .. 999999999. Do not accept master to slave delay (delayMS — from Sync message) or slave to master delay (delaySM — from Delay Response message) if greater than this value (nanoseconds). 0 = not used. So like, if the delay is too big, we reject it. Simple.

Default: 0

  • servo:max_delay_max_rejected — INT: min: 0. Maximum number of consecutive rejected delay measurements exceeding the maxDelay threshold (servo:max_delay), before slave is reset. 0 = not checked. How many rejections before we reset? This many. 0 means don't check.

Default: 0

  • servo:max_delay_stable_only — BOOLEAN. If servo:max_delay is set, perform the check only if clock servo has stabilised. Only check when stable? Okay, we love a conditional queen 💅

Default: N

  • servo:max_offset — INT: 0 .. 999999999. Do not reset the clock if offset from master is greater than this value (nanoseconds). 0 = not used. So like, if the offset is too big, don't reset. Got it.

Default: 0

  • global:enable_snmp — BOOLEAN. Enable SNMP agent (if compiled with PTPD_SNMP). SNMP? Only if you compiled with it, bestie 🌿

Default: N

  • global:use_syslog — BOOLEAN. Send log messages to syslog. Disabling this sends all messages to stdout (or specified log file). Syslog or stdout? Your choice. 💙

Default: N

  • global:lock_file — STRING. Lock file location. Where's the lock file? Right here, bestie 🔒

Default: [none]

  • global:auto_lockfile — BOOLEAN. Use mode specific and interface specific lock file (overrides global:lock_file). Auto lock file? It's giving automatic vibes ✨

Default: N

  • global:lock_directory — STRING. Lock file directory: used with automatic mode-specific lock files, also used when no lock file is specified. When lock file is specified, it's expected to be an absolute path. Directory for locks. Absolute path only if you specify one. Periodt.

Default: /var/run

  • global:ignore_lock — BOOLEAN. Skip lock file checking and locking. Ignoring locks? Risky but okay, bestie 🙈

Default: N

  • global:quality_file — STRING. File used to record data about sync packets. Enables recording when set. Quality file? For sync packet data. Set it to enable. 📊

Default: [none]

  • global:quality_file_max_size — INT: min: 0. Maximum sync packet record file size (in kB) — file will be truncated if size exceeds the limit. 0 — no limit. Max size in kB. 0 means no limit. So like, go off, file.

Default: 0

  • global:quality_file_max_files — INT: 0 .. 100. Enable log rotation of the sync packet record file up to n files. 0 — do not rotate. Rotate up to n files. 0 means don't rotate. We love a rotating queen 💅

Default: 0

  • global:quality_file_truncate — BOOLEAN.
  • global:sync_packet_record_file_truncate — bestie, this one is giving “fresh file, who dis?” energy: truncate the sync packet record file every single time it gets (re)opened — that means startup and SIGHUP. Default: N. 💅
  • global:status_file [STRING] — the file where ptpd2 logs its status info. Default: /var/run/ptpd2.status. 💖
  • global:log_status [BOOLEAN] — turn writing status information to that file on or off. Default: N.
  • global:status_update_interval [INT: 1 .. 30] — how often the status file gets updated, in seconds. Default: 1.
  • global:log_file [STRING] — set the log file path for the event log. The way that setting this literally enables logging to file? Iconic. Default: [none]. ✨
  • global:log_file_max_size [INT: min: 0 ] — maximum log file size in kB. If the size exceeds the limit, the log file will be truncated. 0 means no limit. Default: 0.
  • global:log_file_max_files [INT: 0 .. 100] — enable log rotation of the sync packet record file up to n files. 0 means do not rotate. Default: 0.
  • global:log_file_truncate [BOOLEAN] — truncate the log file every time it’s (re)opened: startup and SIGHUP. Default: N.
  • global:log_level [SELECT] — specify the log level, aka only messages at this priority or higher 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] — specify the statistics log file path. Setting this enables logging of statistics, but it can be overridden with global:log_statistics. Default: [none]. 🎀
  • global:statistics_log_interval [INT: min: 0 ] — log timing statistics every n seconds for Sync and Delay messages (0 means log all). Default: 0.
  • global:statistics_file_max_size [INT: min: 0 ] — maximum statistics log file size in kB. If the size exceeds the limit, the log file will be truncated. 0 means no limit. Default: 0.
  • global:statistics_file_max_files [INT: 0 .. 100] — enable log rotation of the statistics file up to n files. 0 means do not rotate. Default: 0.
  • global:statistics_file_truncate [BOOLEAN] — truncate the statistics file every time it’s (re)opened: startup and SIGHUP. Default: N.
  • global:dump_packets [BOOLEAN] — dump the contents of every PTP packet. Yes, every single one. Default: N. 👑
  • global:verbose_foreground [BOOLEAN] — run in foreground with statistics and all messages logged to stdout. This overrides log file and statistics file settings and disables syslog. Default: N.
  • global:foreground [BOOLEAN] — run in foreground. This is ignored when global:verbose_foreground is set. Default: N.
  • global:log_statistics [BOOLEAN] — 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] — 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)
    • default: datetime
  • global:periodic_updates [BOOLEAN] — 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] — bind the 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] — 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 ] — delay in 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] — enable NTPd integration. Default: N.
  • ntpengine:control_enabled [BOOLEAN] — enable control over the local NTPd daemon. Default: N.
  • ntpengine:check_interval [INT: 5 .. 600] — NTP control check interval in seconds. Default: 15.
  • ntpengine:key_id [INT: 0 .. 65535] — NTP key number. It must be configured as a trusted control key in ntp.conf, and it must be non-zero for the ntpengine:control_enabled setting to take effect. Default: 0.
  • ntpengine:key [STRING] — NTP key (plain text, max. 20 characters). It must match the key configured in ntpd’s keys file, and it must be non-zero for the ntpengine:control_enabled setting to take effect. Default: [none]. 🔐

🐛 BUGS 🐛

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)

💖 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

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

And that’s the whole vibe, bestie. This page is from version 2.3.1, dated June, 2015, and it’s the ptpd2.conf(5) manual — slay, you made it to the end. 💅✨

📦 where this page comes from