PTP4l(8)

📦
version 4.4 · 4 versions
, in centos-stream 9

Bestie, welcome to ptp4l(8) from the System Manager's Manual — aka the PTP Boundary/Ordinary/Transparent Clock page. ✨ This one is lowkey iconic, so grab a snack. 🍓

🌸 NAME 🌸

ptp4l — PTP Boundary/Ordinary/Transparent Clock 💅

✨ SYNOPSIS ✨

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

🦋 DESCRIPTION 🦋

Okay so ptp4l is the Linux implementation of the Precision Time Protocol (PTP) according to IEEE standard 1588. It is literally giving Boundary Clock (BC), Ordinary Clock (OC), and Transparent Clock (TC) energy. 👑 No cap.

💖 OPTIONS 💖

  • -A — Select the delay mechanism automatically. Start with E2E and switch to P2P when a peer delay request is received. 🌀
  • -E — Select the delay request-response (E2E) mechanism. This is the default mechanism. All clocks on a single PTP communication path must use the same mechanism. A warning will be printed when a peer delay request is received on a port using the E2E mechanism.
  • -P — Select the peer delay (P2P) mechanism. A warning will be printed when a delay request is received on a port using the P2P mechanism.
  • -2 — Select the IEEE 802.3 network transport. 🛰️
  • -4 — Select the UDP IPv4 network transport. This is the default transport.
  • -6 — Select the UDP IPv6 network transport.
  • -H — Select hardware time stamping. All ports specified by the -i option and in the configuration file must be attached to the same PTP hardware clock (PHC). This is the default time stamping. ⏱️
  • -S — Select the software time stamping.
  • -L — Select the legacy hardware time stamping.
  • -f config — Read configuration from the specified file. No configuration file is read by default.
  • -i interface — Specify a PTP port; it may be used multiple times. At least one port must be specified by this option or in the configuration file.
  • -p phc-device — (This option is deprecated.) Before Linux kernel v3.5 there was no way to discover the PHC device associated with a network interface. This option specifies the PHC device (e.g. /dev/ptp0) to be used when running on legacy kernels.
  • -s — Enable the clientOnly mode.
  • -l print-level — Set the maximum syslog level of messages which should be printed or sent to the system logger. The default is 6 (LOG_INFO).
  • -m — Print messages to the standard output.
  • -q — Don't send messages to the system logger.
  • -v — Prints the software version and exits.
  • -h — Display a help message. 🫶

🌈 LONG OPTIONS 🌈

Each and every configuration file option (see below) may also appear as a "long" style command line argument. For example, the clientOnly option may be set using either of these two forms. 🎀

--clientOnly 1   --clientOnly=1

Option values given on the command line override values in the global section of the configuration file.

🧚 CONFIGURATION FILE 🧚

The configuration file is divided into sections. Each section starts with a line containing its name enclosed in brackets and it follows with settings. Each setting is placed on a separate line; it contains the name of the option and the value separated by whitespace characters. Empty lines and lines starting with # are ignored.

There are three different section types. 💫

  1. The global section (indicated as [global]) sets the program options, clock options and default port options. Other sections are port specific sections and they override the default port options.
  2. Port sections give the name of the configured port (e.g. [eth0]). Ports specified in the configuration file don't need to be specified by the -i option. An empty port section can be used to replace the command line option.
  3. Tables for configuring unicast discovery begin with [unicast_master_table].

See UNICAST DISCOVERY OPTIONS, below. 👀

🎀 PORT OPTIONS 🎀

  • active_key_id — Used in conjunction with spp and sa_file directives to specify which key from the spp defined Security Association should be used for outbound icv calculations. All Security Associations are read from the file specified by sa_file. Requires spp and sa_file directives. Must be in the range of 1 to 2^32-1, inclusive. The default is 0 (disabled).
  • allowedLostResponses — The number of missed peer delay responses before the asCapable variable is reset. The default is 3.
  • announceReceiptTimeout — The number of missed Announce messages before the last Announce messages expires. The default is 3.
  • boundary_clock_jbod — When running as a boundary clock (that is, when more than one network interface is configured), ptp4l performs a sanity check to make sure that all of the ports share the same hardware clock device. This option allows ptp4l to work as a boundary clock using "just a bunch of devices" that are not synchronized to each other. For this mode, the collection of clocks must be synchronized by an external program, for example phc2sys(8) in "automatic" mode. The default is 0 (disabled).
  • cmlds.client_address — Specifies the source address for the UNIX domain socket that receives peer delay measurement when using the "COMMON_P2P" delay mechanism. The default is /var/run/cmlds_client.
  • cmlds.domainNumber — Specifies the domainNumber message field for communications with the local Common Mean Link Delay Service, used with the "COMMON_P2P" delay mechanism. The default is 0.
  • cmlds.majorSdoId — Specifies the transportSpecific message field for communications with the local Common Mean Link Delay Service, used with the "COMMON_P2P" delay mechanism. The default is 2.
  • cmlds.port — Specifies the port number of local Common Mean Link Delay Service from which to accept delay measurements. The range of valid port numbers is one to 65535, but the special value zero configures the port number of the port requesting the measurements. The default is 0, meaning the requesting port number.
  • cmlds.server_address — Specifies the UNIX domain socket address of the local Common Mean Link Delay Service, for use with the "COMMON_P2P" delay mechanism. The default is /var/run/cmlds_server.
  • delayAsymmetry — The time difference in nanoseconds of the transmit and receive paths. This value should be positive when the server-to-client propagation time is longer and negative when the client-to-server time is longer. The default is 0 nanoseconds.
  • delay_filter — Select the algorithm used to filter the measured delay and peer delay. Possible values are moving_average and moving_median. The default is moving_median.
  • delay_filter_length — The length of the delay filter in samples. The default is 10.
  • delay_mechanism — Select the delay mechanism. Possible values are Auto, COMMON_P2P, E2E, P2P, and NONE. The default is E2E.
  • delay_response_timeout — The number of delay response messages that may go missing before triggering a synchronization fault. Setting this option to zero will disable the delay response timeout. The default is 0 or disabled.
  • egressLatency — Specifies the difference in nanoseconds between the actual transmission time at the reference plane and the reported transmit time stamp. This value will be added to egress time stamps obtained from the hardware. The default is 0.
  • rh_estimate_sync_timestamp — This is a RHEL-specific experimental option which can be renamed, removed, or the functionality changed, in a future minor update. Enables ptp4l to provide in two-step sync messages an estimated transmit time stamp instead of zero. The PN transport needs this option to be enabled. The default is 0 (disabled). 🙈
  • fault_badpeernet_interval — The time in seconds between the detection of a peer network misconfiguration and the fault being reset. The port is disabled for the duration of the interval. The value is in seconds and the special key word ASAP will let the fault be reset immediately. The default is 16 seconds.
  • fault_reset_interval — The time in seconds between the detection of a port's fault and the fault being reset. This value is expressed as a power of two. Setting this value to -128 or to the special key word "ASAP" will let the fault be reset immediately. The default is 4 (16 seconds).
  • follow_up_info — Include the 802.1AS data in the Follow_Up messages if enabled. The default is 0 (disabled).
  • G.8275.portDS.localPriority — The Telecom Profiles (ITU-T G.8275.1 and G.8275.2) specify an alternate Best Master Clock Algorithm (BMCA) with a unique data set comparison algorithm. The value of this option is associated with Announce messages arriving on a particular port and is used as a tie breaker whenever clockClass, clockAccuracy, offsetScaledLogVariance, and priority2 are equal. This option is only used when "dataset_comparison" is set to "G.8275.x". The default value is 128.
Warning: the BMCA is guaranteed to produce a spanning tree (that is, a timing network without loops) only when using the default values of G.8275.defaultDS.localPriority and G.8275.portDS.localPriority. Careful network engineering is needed when using non-default values. ⚠️
  • hybrid_e2e — Enables the "hybrid" delay mechanism from the draft Enterprise Profile. When enabled, ports in the client state send their delay request messages to the unicast address taken from the server's announce message. Ports in the server state will reply to unicast delay requests using unicast delay responses. This option has no effect if the delay_mechanism is set to P2P. The default is 0 (disabled).
  • ignore_transport_specific — By default, incoming messages are dropped if their transportSpecific field does not match the configured value. However, many of transports specified in the 1588 standard mandate ignoring this field. Moreover, some equipment is known to set the reserved bits. Configuring this option as 1 causes this field to be ignored completely on receive. The default is 0.
  • ingressLatency — okay so this one's the gap, in nanoseconds, between the receive time stamp the hardware reports and the actual moment the packet landed at the reference plane 💅 ptp4l subtracts this value from ingress time stamps it gets from the hardware. Default is 0.
  • inhibit_delay_req — literally just: don't send any delay requests 🚫 This needs the asCapable config option set to 'true', iykyk. Super handy when you're running as a designated server who doesn't need to calculate offset from the client. Default is 0 (disabled).
  • inhibit_multicast_service — some unicast mode profiles are insistent that no multicast messages ever get transmitted 🙈 Setting this option inhibits multicast transmission. Default is 0 (multicast enabled).
  • logAnnounceInterval — the mean time interval between Announce messages. Shorter interval = ptp4l reacts faster to changes in the client/server hierarchy, periodt. It should be the same across the whole domain, bestie. Specified as a power of two in seconds. Default is 1 (2 seconds).
  • logMinDelayReqInterval — the minimum permitted mean time interval between Delay_Req messages. Shorter interval makes ptp4l react faster to changes in the path delay ✨ Specified as a power of two in seconds. Default is 0 (1 second).
  • logMinPdelayReqInterval — the minimum permitted mean time interval between Pdelay_Req messages. Specified as a power of two in seconds. Default is 0 (1 second).
  • logSyncInterval — the mean time interval between Sync messages. A shorter interval may improve accuracy of the local clock 👑 Specified as a power of two in seconds. Default is 0 (1 second).
  • masterOnly — ⚠️ okay bestie, heads up: this option is deprecated and will be removed in a future release. Use "serverOnly" instead.
  • min_neighbor_prop_delay — lower limit for peer delay, in nanoseconds. If the estimated peer delay is smaller than this value, the port gets marked as not 802.1AS capable 💀
  • neighborPropDelayThresh — upper limit for peer delay, in nanoseconds. If the estimated peer delay is greater than this value, the port is marked as not 802.1AS capable.
  • network_transport — picks the network transport 🌈 Possible values are UDPv4, UDPv6, L2 (Ethernet), and PN (PROFINET). The PN transport is experimental in RHEL and it can be removed or changed in a future minor update — so don't get too attached. Default is UDPv4.
  • net_sync_monitor — enables the NetSync Monitor (NSM) protocol ✨ The NSM protocol lets a station measure how well another node is synchronized. The monitor sends a unicast delay request to the node, which replies unconditionally with unicast delay response, sync, and follow up messages. If the monitor is synchronized to the GM, it can use the time stamps in the message to estimate the node's offset. This option requires that the 'hybrid_e2e' option be enabled as well. Default is 0 (disabled).
  • operLogPdelayReqInterval — the Pdelay Request messages interval to be used once the clock enters the SERVO_LOCKED_STABLE state. If the 'msg_interval_request' option is set, then the local client port will adopt this rate when the local clock enters the "locked stable" state 🔒 Specified as a power of two in seconds, and the default value is 0 (1 second).
  • operLogSyncInterval — the Sync message interval to be requested once the clock enters the SERVO_LOCKED_STABLE state. If 'msg_interval_request' is set, then the local client port will request the remote server to switch to the given message rate via a signaling message containing a Message interval request TLV 📨 Specified as a power of two in seconds, and default value is 0 (1 second).
  • path_trace_enabled — enables the mechanism used to trace the route of the Announce messages 🦋 Default is 0 (disabled).
  • phc_index — specifies the index of the PHC to be used for synchronization with hardware timestamping. This option is useful with virtual clocks running on top of a free-running physical clock (created by writing to /sys/class/ptp/ptp*/n_vclocks) 🕰️ Default is -1, which means the index will be set to the PHC associated with the interface, or the device specified by the -p option.
  • power_profile.2011.grandmasterTimeInaccuracy — specifies the time inaccuracy of the GM, in nanoseconds. Only relevant when power_profile.version is 2011. This value may be changed dynamically using the POWER_PROFILE_SETTINGS_NP management message. Default is -1, meaning unknown inaccuracy 🙈
  • power_profile.2011.networkTimeInaccuracy — specifies the time inaccuracy of the network, in nanoseconds. Only relevant when power_profile.version is 2011. This value may be changed dynamically using the POWER_PROFILE_SETTINGS_NP management message. Default is -1, meaning unknown inaccuracy.
  • power_profile.2017.totalTimeInaccuracy — specifies the sum of the GM, network, and local node inaccuracies, in nanoseconds. Only relevant when power_profile.version is 2017. This value may be changed dynamically using the POWER_PROFILE_SETTINGS_NP management message. Default is -1, meaning unknown inaccuracy 💀
  • power_profile.grandmasterID — specifies an optional, non-zero identification code for the GM. Note that the code is an arbitrary, power profile specific integer — not necessarily related to the clockIdentity in any way 🎀 This value may be changed dynamically using the POWER_PROFILE_SETTINGS_NP management message. Default is 0, meaning unused.
  • power_profile.version — specifies the power profile version to be used. Valid values are "none", "2011", or "2017" ✨ This value may be changed dynamically using the POWER_PROFILE_SETTINGS_NP management message. Default is "none".
  • ptp_dst_ipv4 — the IPv4 address to which PTP messages should be sent. Only relevant with UDPv4 transport. Default is 224.0.1.129 📬
  • p2p_dst_ipv4 — the IPv4 address to which peer delay messages should be sent. Only relevant with UDPv4 transport. Default is 224.0.0.107.
  • ptp_dst_ipv6 — the IPv6 address to which PTP messages should be sent. The second byte of the address is substituted with udp6_scope 👀 Only relevant with UDPv6 transport. Default is FF0E:0:0:0:0:0:0:181.
  • p2p_dst_ipv6 — the IPv6 address to which peer delay messages should be sent. Only relevant with UDPv6 transport. Default is FF02:0:0:0:0:0:0:6B.
  • ptp_dst_mac — the MAC address to which PTP messages should be sent. Only relevant with L2 transport. Default is 01:1B:19:00:00:00 🌸
  • p2p_dst_mac — the MAC address to which peer delay messages should be sent. Only relevant with L2 transport. Default is 01:80:C2:00:00:0E.
  • serverOnly — setting this option to one (1) prevents the port from entering the client state. On top of that, the local clock will ignore Announce messages received on this port 🚫 This option's intended use is to support the Telecom Profiles according to ITU-T G.8265.1, G.8275.1, and G.8275.2. The default value is zero or false.
  • spp — specifies the Security Parameters Pointer of the desired Security Association to be used for Authentication TLV support for a given port 🔐 Any port with an assigned spp will attach Authentication TLVs to all outbound messages and check for Authentication TLVs on all inbound messages in accordance to the corresponding security association sourced via the sa_file directive. Outbound Authentication TLVs are generated using the key specified by active_key_id. Not compatible with one step ports or advertised versions less then PTPv2.1 💀 Requires sa_file and active_key_id directives. Must be in the range of 0 to 255, inclusive. Default is -1 (disabled).
  • syncReceiptTimeout — the number of sync/follow up messages that may go missing before triggering a Best Master Clock election 🗳️ This option is used for running in gPTP mode according to the 802.1AS-2011 standard. Setting this option to zero will disable the sync message timeout. Default is 0 or disabled.
  • transportSpecific — the transport specific field. Must be in the range 0 to 255. Default is 0.
  • tsproc_mode — selects the time stamp processing mode used to calculate offset and delay 🧮 Possible values are filter, raw, filter_weight, raw_weight. Raw modes perform well when the rate of sync messages (logSyncInterval) is similar to the rate of delay messages (logMinDelayReqInterval or logMinPdelayReqInterval). Weighting is useful with larger network jitters (e.g. software time stamping). Default is filter.
  • rh_subdomainUUID — ⚠️ this is a RHEL-specific experimental option which can be renamed, removed, or the functionality changed, in a future minor update.

It specifies the UUID of the PTCP subdomain used with the PN transport. Default is 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00 (which indicates an unknown subdomain).

  • udp_ttl — specifies the Time to live (TTL) value for IPv4 multicast messages and the hop limit for IPv6 multicast messages. This option is only relevant with the IPv4 and IPv6 UDP transports. Default is 1 to restrict the messages sent by ptp4l to the same subnet 🏠
  • unicast_listen — when enabled, this option allows the port to grant unicast message contracts ✨ Incoming requests for will be granted limited only by the amount of memory available. Default is 0 (disabled).
  • unicast_master_table — when set to a positive integer, this option specifies the table id to be used for unicast discovery 📋 Each table lives in its own section and has a unique, positive numerical ID. Entries in the table are a pair of transport type and protocol address. Default is 0 (unicast discovery disabled).

okay so last port-option baddie before we slide into clock business:

  • unicast_req_duration — this is the service time in seconds that gets requested during unicast discovery. Quick note, bestie: the remote node can totally grant a different duration, so don’t act surprised 💅. The default is 3600 seconds, aka one hour ⏰.

✨ PROGRAM AND CLOCK OPTIONS ✨

These are the main-character knobs for how ptp4l thinks about itself, its clock, and the whole timing vibe 🕰️✨

  • asCapable — if set to 'true', all the checks that can unset the asCapable variable (as described in Section 10.2.4.1 of 802.1AS) get skipped. If set to 'auto', asCapable starts as 'false' and flips to 'true' after the relevant checks pass. Default is 'auto' 🎀.
  • assume_two_step — treat one-step responses as two-step if this is enabled. It’s the workaround for buggy 802.1AS switches, no cap 😭. Default is 0 (disabled).
  • BMCA — this option enables static roles for server and client devices instead of running the best master clock algorithm (BMCA) described in the 1588 profile. It’s giving speed-up energy for servers and clients when you already know the roles in advance 🔥. When set to noop, the traditional BMCA algorithm used by 1588 is skipped. masterOnly and clientOnly are then used to determine the server or client role for the device. In a bridge, clientOnly (which is a global option) can be set so all ports assume the client role. masterOnly (which is a per-port config option) can then be used to set individual ports to take on the server role. Default is 'ptp', which runs the BMCA-related state machines 👑.
  • check_fup_sync — because packet reordering can happen in the network, in the hardware, or in the networking stack, a follow-up message can appear to arrive in the application before the matching sync message. This is a normal occurrence, and the sequenceID message field makes sure matching still works, so ptp4l accepts out-of-order packets 🫶. This option adds an extra check using the software time stamps from the networking stack to verify that the sync message did arrive first. It’s only useful if you do not trust the sequence IDs generated by the server. Default is 0 (disabled).
  • clientOnly — the local clock is a client-only clock if enabled. Default is 0 (disabled) 🌸.
  • clockAccuracy — the clockAccuracy attribute of the local clock. It’s used in the PTP server selection algorithm. Default is 0xFE ⭐.
  • clockClass — the clockClass attribute of the local clock. It denotes the traceability of the time distributed by the grandmaster clock. Default is 248 💖.
  • clock_class_threshold — the maximum clock class value from master that’s acceptable to a subordinate clock, beyond which it moves out of lock state. Default value is 248 🦋.
  • clockIdentity — the clockIdentity attribute of the local clock. It’s an 8-octet array and should be written in textual form in this configuration, see the default. It should be unique since it’s used to identify the specific clock 🎀. If default is used or if it’s not set at all, the clockIdentity will be automatically generated. Default is "000000.0000.000000" ✨.
  • clock_servo — the servo used to synchronize the local clock. Valid values are "pi" for a PI controller, "linreg" for an adaptive controller using linear regression, "ntpshm" and "refclock_sock" for the NTP SHM and chrony SOCK reference clocks respectively, to allow another process to synchronize the local clock, and "nullf" for a servo that always dials frequency offset zero (for use in SyncE nodes) 💅. Default is "pi".
  • clock_type — specifies the kind of PTP clock. Valid values are "OC" for ordinary clock, "BC" for boundary clock, "P2P_TC" for peer-to-peer transparent clock, and "E2E_TC" for end-to-end transparent clock. A multi-port ordinary clock will automatically be configured as a boundary clock. Default is "OC" 👑.
  • dataset_comparison — specifies the method used when comparing data sets during the Best Master Clock Algorithm. Possible values are "ieee1588" and "G.8275.x". Default is "ieee1588" 🔍.
  • domainNumber — the domain attribute of the local clock. Default is 0 🌈.
  • dscp_event — defines the Differentiated Services Codepoint (DSCP) to be used for PTP event messages. Must be a value between 0 and 63. There are several media streaming standards out there that require specific values for this option. For example 46 (EF PHB) in AES67 or 48 (CS6 PHB) in RAVENNA. Default is 0 🍓.
  • dscp_general — defines the Differentiated Services Codepoint (DSCP) to be used for PTP general messages. Must be a value between 0 and 63. There are several media streaming standards out there that recommend specific values for this option. For example 34 (AF41 PHB) in AES67 or 46 (EF PHB) in RAVENNA. Default is 0 🧚.
  • first_step_threshold — the maximum offset the servo will correct by changing the clock frequency (phase when using nullf servo) instead of stepping the clock. This is only applied on the first update. It’s specified in seconds. When set to 0.0, the servo won’t step the clock on start. Default is 0.00002 (20 microseconds) ⏱️. This option used to be called pi_f_offset_const.
  • free_running — don’t adjust the local clock if enabled. Default is 0 (disabled) 🦋.
  • freq_est_interval — the time interval over which the ratio of the local and peer clock frequencies is estimated. It’s specified as a power of two in seconds. Default is 1 (2 seconds) 💜.
  • G.8275.defaultDS.localPriority — the Telecom Profiles (ITU-T G.8275.1 and G.8275.2) specify an alternate Best Master Clock Algorithm (BMCA) with a unique data set comparison algorithm. The value of this option is associated with the local clock and is used as a tie breaker whenever clockClass, clockAccuracy, offsetScaledLogVariance, and priority2 are equal. This option is only used when "dataset_comparison" is set to "G.8275.x". Default value is 128 👀.
Warning: the BMCA is guaranteed to produce a spanning tree (that is, a timing network without loops) only when using the default values of G.8275.defaultDS.localPriority and G.8275.portDS.localPriority. Careful network engineering is needed when using non-default values ⚠️.
  • gmCapable — if this option is enabled, then the local clock is able to become grand master. This is only for use with 802.1AS clocks and has no effect on 1588 clocks. Default is 1 (enabled) 🌟.
  • ignore_source_id — this disables source port identity checking for Sync and Follow_Up messages. It’s useful when announce messages are disabled in the server and the client doesn’t have any way to know the server’s identity. Default is 0 (disabled) 🙈.
  • inhibit_announce — this disables the timer for announce messages (i.e. FD_MANNO_TIMER) and also the announce message timeout timer (i.e. FD_ANNOUNCE_TIMER). It’s used by the Automotive profile as part of switching over to a static BMCA 🔧. If this option is enabled, ignore_source_id has to be enabled in the client because it has no way to identify the server in the Sync and Follow_Up messages. Default is 0 (disabled).
  • initial_delay — the initial path delay of the clock in nanoseconds, used for synchronization of the clock before the delay is measured using the E2E or P2P delay mechanism. If set to 0, the clock will not be updated until the delay is measured. Default is 0 ⏳.
  • interface_rate_tlv — when the client and server are operating at different interface rates, delay asymmetry caused by the different interface rate needs to be compensated. The server sends its interface rate using the interface rate TLV as per G.8275.2 Annex D. Default is 0 (does not support interface rate tlv) 📡.
  • hwts_filter — select the hardware time stamp filter setting mode. Possible values are normal, check, and full. normal mode sets the filters as needed. check mode only checks but does not set. full mode sets the receive filter to mark all packets with hardware time stamp, so all applications can get them. Default is normal 🎚️.
  • kernel_leap — when a leap second is announced, let the kernel apply it by stepping the clock instead of correcting the one-second offset with servo, which would correct the one-second offset slowly by changing the clock frequency (unless the step_threshold option is set to correct such offset by stepping). Relevant only with software time stamping. Default is 1 (enabled) ⏰.
  • logging_level — the maximum logging level of messages that should be printed. Default is 6 (LOG_INFO) 📝.
  • manufacturerIdentity — the manufacturer id, which should be an OUI owned by the manufacturer. Default is 00:00:00 🏷️.
  • max_frequency — the maximum allowed frequency adjustment of the clock in parts per billion (ppb). This is an additional limit to the maximum allowed by the hardware. When set to 0, the hardware limit will be used. Default is 900000000 (90%) 🔥. This option used to be called pi_max_frequency.
  • maxStepsRemoved — when using this option, if the value of stepsRemoved of an Announce message is greater than or equal to the value of maxStepsRemoved, the Announce message is not considered in the operation of the BMCA. Default value is 255 🛑.
  • message_tag — the tag added to all messages printed to the standard output or system log. If the tag contains the string "{level}", it will be replaced with the log level of the message as a number 🔖. Default is an empty string (which cannot be set in the configuration file as the option requires an argument).
  • msg_interval_request — bestie, when you turn this on it triggers an adjustment to the Sync and peer delay request message intervals the moment the clock servo transitions into the SERVO_LOCKED_STABLE state ✨. The Sync interval gets adjusted via the signaling mechanism, while the pdelay request interval is simply adjusted locally (no cap, that's just how it works). The new values come from the operLogSyncInterval and operLogPdelayReqInterval options respectively. Default is 0 (disabled) 🎀
  • ntpshm_segment — the number of the SHM segment used by the ntpshm servo. Default is 0 🫶
  • offsetScaledLogVariance — the offsetScaledLogVariance attribute of the local clock. It characterizes the stability of the clock. Default is 0xFFFF 💜
  • pi_integral_const — the integral constant of the PI controller 🧚. When set to 0.0, the integral constant gets set by this formula from the current sync interval. Default is 0.0.
ki = min(ki_scale * sync^ki_exponent, ki_norm_max / sync)
  • pi_integral_exponent — the ki_exponent constant in the formula used to set the integral constant of the PI controller from the sync interval. Default is 0.4 ⭐
  • pi_integral_norm_max — the ki_norm_max constant in that same formula used to set the integral constant of the PI controller from the sync interval. Default is 0.3 🌸
  • pi_integral_scale — the ki_scale constant in the formula used to set the integral constant of the PI controller from the sync interval. When set to 0.0, the value will be selected from 0.3 and 0.001 for the hardware and software time stamping respectively 👑. Default is 0.0.
  • pi_proportional_const — the proportional constant of the PI controller 💅. When set to 0.0, the proportional constant will be set by this formula from the current sync interval. Default is 0.0.
kp = min(kp_scale * sync^kp_exponent, kp_norm_max / sync)
  • pi_proportional_exponent — the kp_exponent constant in the formula used to set the proportional constant of the PI controller from the sync interval. Default is -0.3 🦋
  • pi_proportional_norm_max — the kp_norm_max constant in the formula used to set the proportional constant of the PI controller from the sync interval. Default is 0.7 🌈
  • pi_proportional_scale — the kp_scale constant in the formula used to set the proportional constant of the PI controller from the sync interval. When set to 0.0, the value will be selected from 0.7 and 0.1 for the hardware and software time stamping respectively 🍓. Default is 0.0.
  • productDescription — the product description string 🏷️. Allowed values must be of the form manufacturerName;modelNumber;instanceIdentifier and contain at most 64 utf8 symbols. Default is ";;".
  • priority1 — the priority1 attribute of the local clock. It's used in the PTP server selection algorithm, and lower values take precedence 👀. Must be in the range 0 to 255. Default is 128.
  • priority2 — the priority2 attribute of the local clock. Also used in the PTP server selection algorithm, lower values take precedence. Must be in the range 0 to 255. Default is 128 💖
  • ptp_minor_version — this option sets the minorVersionPTP in the common PTP message header. The default (specific to the installed linuxptp package) is 0, but setting sa_file forces the version to 1 ⚠️
  • refclock_sock_address — the address of the UNIX domain socket to be used by the refclock_sock servo. Default is /var/run/refclock.ptp.sock 🎀
  • revisionData — the revision description string which contains the revisions for node hardware (HW), firmware (FW), and software (SW) 🔧. Allowed values are of the form HW;FW;SW and contain at most 32 utf8 symbols. The default is an ";;".
  • sa_file — specifies the location of the file containing Security Associations used for immediate security processing of the Authentication TLV in support of the optional security mechanism defined in ieee1588-2019 ch 14.16 🔐. See SECURITY ASSOCIATION OPTIONS for info on how this file should be formatted. spp and active_key_id should be specified for each port to indicate which Security Association from the sa_file should be used. Default is an empty string.
  • sanity_freq_limit — the maximum allowed frequency offset between uncorrected clock and the system monotonic clock, in parts per billion (ppb) 😤. This is used as a sanity check of the synchronized clock. When a larger offset is measured, a warning message will be printed and the servo will be reset. If the frequency correction set by ptp4l changes unexpectedly between updates of the clock (e.g. due to another process trying to control the clock), a warning message will be printed. When set to 0, the sanity check is disabled. Default is 200000000 (20%).
  • servo_num_offset_values — the number of offset values considered in order to transition from the SERVO_LOCKED to the SERVO_LOCKED_STABLE state 🦋. The transition occurs once the last servo_num_offset_values offsets are all below the servo_offset_threshold value. Default value is 10.
  • servo_offset_threshold — the offset threshold used in order to transition from the SERVO_LOCKED to the SERVO_LOCKED_STABLE state ✨. The transition occurs once the last servo_num_offset_values offsets are all below the threshold value. The default value of offset_threshold is 0 (disabled).
  • slave_event_monitor — specifies the address of a UNIX domain socket for event monitoring 👀. A local monitoring client bound to this address will receive SLAVE_RX_SYNC_TIMING_DATA and SLAVE_DELAY_TIMING_DATA_NP TLVs. Default is the empty string (disabled).
  • slaveOnly — 🚨 this option is deprecated and will be removed in a future release. Use clientOnly instead, bestie.
  • socket_priority — configure the SO_PRIORITY of sockets 🔧. This is to support cases where a user wants to route ptp4l traffic using Linux qdiscs for the purpose of traffic shaping. This option is only available with the IEEE 802.3 transport (the -2 option) and is silently ignored when using the UDP IPv4/6 network transports. Must be in the range of 0 to 15, inclusive. Default is 0.
  • step_threshold — the maximum offset the servo will correct by changing the clock frequency (phase when using nullf servo) instead of stepping the clock ⏱️. When set to 0.0, the servo will never step the clock except on start. It's specified in seconds. Default is 0.0. This option used to be called pi_offset_const.
  • step_window — when set, indicates the number of Sync events after a clock step that the clock will not do any frequency or step adjustments 🙈. This is used in situations where clock stepping is unable to happen instantaneously so there is a lag before the timestamps can settle properly to reflect the clock step. Default is 0 (disabled).
  • summary_interval — the time interval in which summary statistics of the clock are printed 📊. It's specified as a power of two in seconds. The statistics include offset root mean square (RMS), maximum absolute offset, frequency offset mean and standard deviation, and path delay mean and standard deviation. The units are nanoseconds and parts per billion (ppb). If there is only one clock update in the interval, the sample will be printed instead of the statistics. The messages are printed at the LOG_INFO level. Default is 0 (1 second).
  • tc_spanning_tree — when running as a Transparent Clock, increment the "stepsRemoved" field of Announce messages that pass through the switch 🌳. Enabling this option ensures that PTP message loops never form, provided the switches all implement this option together with the BMCA 👑
  • timeSource — the time source is a single byte code that gives an idea of the kind of local clock in use 🕰️. The value is purely informational, having no effect on the outcome of the Best Master Clock algorithm, and is advertised when the clock becomes grand master.
  • time_stamping — the time stamping method to be used. The allowed values are hardware, software, legacy, onestep, and p2p1step. Default is hardware ⚡
  • twoStepFlag — enable two-step mode for sync messages. One-step mode can be used only with hardware time stamping 🚨. Default is 1 (enabled).
  • tx_timestamp_timeout — the number of milliseconds to poll waiting for the tx time stamp from the kernel when a message has recently been sent. Default is 10 ⏳
  • udp6_scope — specifies the desired scope for the IPv6 multicast messages 🌐. This will be used as the second byte of the primary address. This option is only relevant with IPv6 transport. See RFC 4291. Default is 0x0E for the global scope.
  • uds_address — specifies the address of the UNIX domain socket for receiving local management messages. Default is /var/run/ptp4l 🫶
  • uds_file_mode — file mode of the UNIX domain socket used for receiving local management messages 🔐. The mode should be specified as an octal number, i.e. it should start with a 0 literal. The default mode is 0660.
  • uds_ro_address — specifies the address of the second UNIX domain socket for receiving local management messages, which is restricted to GET actions and does not forward messages to other ports 👀. Access to this socket can be given to untrusted applications for monitoring purposes. Default is /var/run/ptp4lro.
  • uds_ro_file_mode — file mode of the second (read-only) UNIX domain socket used for receiving local management messages. The mode should be specified as an octal number, i.e. it should start with a 0 literal. The default mode is 0666 🎀
  • use_syslog — print messages to the system log if enabled. Default is 1 (enabled) 📝
  • userDescription — okay so this is the user description string 🎀 allowed values look like name;location and it can hold at most 128 utf8 symbols. default is an empty string (iykyk, nothing there).
  • utc_offset — the current offset between TAI and UTC ⏰ default is 37. no cap, that's the number.
  • verbose — prints messages to the standard output if enabled 💬 default is 0 (disabled, so it's quiet bestie).
  • write_phase_mode — this one unlocks the "write phase" feature of a PTP Hardware Clock ✨ if the device supports it, this mode uses the hardware's built-in phase offset control instead of frequency offset control 👑 default value is 0 (disabled).

🌈 UNICAST DISCOVERY OPTIONS 🌈

  • L2|UDPv4|UDPv6 — every table entry specifies the transport type and the network address of a potential remote server 💅 if you list multiple servers, then unicast negotiation gets performed with each of them. slay, multitasking.
  • logQueryInterval — this configures the time to wait between unicast negotiation attempts ⏳ it's specified as a power of two in seconds. default is 0 (which means 1 second, cute).
  • peer_address — specifies the unicast address of the peer for use with the peer to peer delay mechanism 🦋 if you set it, the port owning the table will negotiate unicast peer delay responses from the machine at that given remote address; otherwise the port just sends multicast peer delay requests.
  • table_id — each table must begin with a unique, positive table ID 🔢 the port that claims a given table does so by including the ID as the value of its unicast_master_table option. periodt.

🔐 SECURITY ASSOCIATION OPTIONS 🔐

  • spp — each security association must begin with a unique spp 💜 the port claims a given security association by including the spp as the value of its spp option. must be in the range of 0 to 255, inclusive.
  • seqid_window — this defines how far the sequence id of an incoming sync/follow_up message can advance from the last successfully processed sync/follow_up before it gets considered a replayed message 👀 sync/follow_up seqid tracking is reset on port state change and updated upon successful processing. when set to zero, no seqid checking happens at all. must be in the range of 0 to 32767 (0x7FFF) inclusive. default value is 3.
  • allow_mutable — this allows for mutable correction fields if on path authentication tlv support isn't possible 🙈 this option is NOT recommended — it leaves the correction field unprotected. default value is 0 (disabled).
  • key (format: id type length value) — each security association must have at least one key entry, bestie, like at minimum one 🗝️ these entries should use the format id type length value:
    • Key id: must be in the range of 1 to 2^32-1, inclusive.
    • Key type: allowed are SHA256-128, SHA256, AES128, AES256.
    • Key length: optional verification key length in octets. used to verify the key value is of the length specified.
    • Key value: can be read as ASCII characters with the "ASCII:" prefix, as a hexadecimal number with the "HEX:" prefix, or as a Base64 encoded string with the "B64:" prefix. if no prefix is included, ASCII is assumed. key values should be randomally generated if possible. ciphers (AES) require the key length to match the cipher length (ie AES-128 requires key of 128 bits or 16 bytes).

💫 Example 💫

the following is an example of a security associations file:

[security_association]
spp 0
allow_mutable 1
1 SHA256-128 HEX:F8ADC6B8B8E9AA709106BA42481EC9E29607334DE2C3C737A11A12931DB27F8C
2 SHA256 32 HEX:EE91D469B3A8ADC6AC8EB28E21794C706E08FDE48863828A7B0281AFCA81B17D

[security_association]
spp 1
seqid_window 20
1 AES128 HEX:FAF48EBA01E7C5966A76CB787AED4E7B
2 AES256 B64:PKTF9VQz94qPaoAzW4eE3JtFoQ8Ov1OTQSojalWyMbs=
3 SHA256 26 abcdefghijklmnopqrstuvwxyz

⏱️ TIME SCALE USAGE ⏱️

when ptp4l acts as the domain server, it either uses the PTP or the UTC time scale depending on the time stamping mode 🌍 in software and legacy time stamping modes it announces Arbitrary time scale mode, which is effectively UTC here. in hardware time stamping mode it announces use of PTP time scale. two whole vibes, one program.

when ptp4l is the domain server using hardware time stamping, it's up to phc2sys to maintain the correct offset between UTC and PTP times 🫶 see phc2sys(8) manual page for more details.

🧵 KTHREAD PRIORITY 🧵

so in the case of the following log:

timed out while polling for tx timestamp increasing
tx_timestamp_timeout or increasing kworker priority may correct
this issue, but a driver bug likely causes it

one possible cause is that the kworker which processes timestamps is being starved 😭 the system admin might try manually increasing the priority of the kworker.

many device drivers use kworker threads created by the PTP stack 🌸 such kworkers are named:

ptp<decimal number of clock>

the system admin can manually bump the priority of the kworker process using chrt 💪

Example:

pgrep -f "ptp[0-9]+" | xargs -I {} sudo chrt -f --pid 75 {}

the Intel ice driver may create multiple kworkers for one physical NIC and names those processes differently 👀

Example for Intel E810 card:

pgrep -f ice-ptp | xargs -I {} sudo chrt -f --pid 75 {}
⚠️ assigning priority needs careful consideration, bestie — assigning too high a priority to any task might make the system unstable. like fr fr, be careful with this one 💀

👑 SEE ALSO 👑

pmc(8), phc2sys(8)

and that's the whole page, you ate that 🎀💖 linuxptp — dated March 2024 ✨ go be iconic with your clocks, bestie 🌈🫶💅

📦 where this page comes from