ptpd2

Runs on:

QNX OS

Options:

Basic daemon and PTP protocol options

If the format section:key is available (e.g., --ptpengine:log_delayreq_override), you can use it to set the option in the configuration file (without the leading --).

?

Displays descriptions of the help options (-H and -h).

-A

--auto-lockfile

Automatically generates names for lock files based on the port mode. This option is useful when you are running multiple instances.

-a

--delay-override

--ptpengine:log_delayreq_override

In client (slave) mode, use the Delay Request message interval specified by -r (or equivalent option) instead of the one announced by the server.

-C

--foreground

--global:foreground=Y

Prevents the daemon from running in the background.

-c path

--config-file path

Specifies the path of the configuration file. For more information, enter ptpd2 -H.

-D

--debug

--global:debug_level

Specifies the debug level. Specify -D (minimal debug information), -DD (detailed information), or -DDD (maximum information). Only available if compiled with RUNTIME_DEBUG.

-d number

--domain number

--ptpengine:domain=number

Specifies the PTP domain number to become part of.

-E

--e2e

--ptpengine:delay_mechanism=E2E

Enables the end-to-end delay mechanism.

-e setting

--explain setting

Displays help for the specified setting. Specify the setting using the configuration file format: section:key.

-F clock_id:port_id

--fp clock_id:port_id

In client (slave) mode, force the server (master) clock identity to the specified ID and ignore announce packets. Specify 0000000000000000:0 (wildcard) to use the clock identity from the first received synchronization packet.

In server (master) mode, don't run BMCA and immediately go to server status. The clock_id:port_id values are ignored.

-f path

--log-file path

--global:logfile=path

Specifies the path of the log file.

-g

--unicast-negotiation

--ptpengine:unicast_negotiation=y

Enables unicast message delivery and interval negotiation using signaling messages, as used by the ITU-T Telecom Profile (G.8265.1). Also enables ptpengine:ip_mode=unicast.

-H

--long-help

Displays detailed help for all settings and behaviors.

-h

--help

Displays basic help.

-I

--reqannounceinterval

In client (slave) mode, after receiving the first sync message, issue a signaling message with announce interval set to -1. If this option is not specified, no signaling message is sent.

-i device

--interface device

--ptpengine:interface=device

Specifies the interface to use (e.g., eth0).

-J number

--max-step number

Specify the maximum offset (in nanoseconds) before stepping the clock.

-K

--resmgr

Enables the ptpd2 resource manager.

-k

--check-config

Checks configuration and then ptpd2 exits. Returns 0 if the configuration is valid.

-L

--ignore-lock

--global:ignore_lock

Skips lock file checks and locking.

-l path

--lockfile path

--global:lock_file=path

Specifies the path of the lock file.

-M

--masteronly

--ptpengine:preset=masteronly

Specifies a clock that is always a server and is passive when a better server is available in the network.

-m

--masterslave

--ptpengine:preset=masterslave

Specifies a clock that can act as server or client. Usually acts as a client unless there is no better server available in the network.

-N

--noswitch

Enables no-switch mode.

-n

-noadjust

--clock:no_adjust

Prevents the clock from being adjusted.

-O

--default-config

Displays the default configuration and then ptpd2 exits. You can use the output as a configuration file.

-o

--servo-optimization

Enables experimental servo optimizations. The interface specified by -i (or equivalent option) must support hardware timestamping. Cannot be used with -Q.

-P

--p2p

--ptpengine:delay_mechanism=P2P

Enables the peer-to-peer delay mechanism.

-p

--print-lockfile

Prints the path to the lock file and then ptpd2 exits. This is useful for obtaining lock file names to include in an initialization script when the names are generated automatically (by specifying -A).

-Q

--sw-timestamps-only

Use only software timestamps. Do not attempt to initialize hardware timestamping.

-q

--disable-signaling

Do not handle signaling messages.

-R directory

--lock-directory directory

--global:lock_directory=directory

Specifies the directory to store lock files in.

-r number

--delay-interval number

--ptpengine:log_delayreq_interval=number

Specifies the Delay Request message interval (log 2).

-S path

--statistics-file path

--global:statistics_file=path

Specifies the path of the statistics file.

-s

--slaveonly

--ptpengine:preset=slaveonly

Specifies a clock that is never a server.

-T

--dot2as

Enables 802.1AS support.

-U

--unicast

--ptpengine:ip_mode=unicast

Specifies unicast operation.

For server-only and hybrid operation, you must also specify unicast destinations (-u or equivalent), unless you specify unicast negotiation (-g or equivalent) for delay request and response.

For client-only and hybrid operation, you must specify unicast destinations if you don't use unicast negotiation.

-u ip-address [,ip-address...]

--unicast-destinations ip-address [,ip-address...]

--ptpengine:unicast-destinations=ip-address [,ip-address...]

Specifies unicast destinations. Requires -U (or equivalent option).

-V

--verbose

--global:verbose_foreground=Y

Runs the daemon in the foreground and logs all messages to standard output.

-v

--version

Prints the version string and then ptpd2 exits.

-X number

--correction-step number

Specifies the correction (in nanoseconds) to add to the offset when stepping the clock.

-x opt[,opt…]

--extra-opts opt[,opt…]

Specifies one or more configuration parameters. Valid values are:

• noSysClkAdj — Disable adjustments to the system clock.
• noPTPClkAdj — Disable adjustments to the PTP clock (if the hardware and driver support it).
• noSetPTPTimeFromSys — Disable initialization of the PTP clock from the system clock (if the hardware and driver support it).
• filename — The path and filename of an .ini file. It configures extra ptpd2 features.

-y

--hybrid

--ptpengine:ip_mode=hybrid

Specifies mixed multicast (for sync and announce) and unicast (for delay request and response) operation. To specify it in the configuration file, include ptpengine:ip_mode=hybrid.

Deprecated options

Description:

The ptpd2 daemon implements the Precision Time Protocol (PTP) Version 2 as defined by the IEEE 1588-2008 standard. PTP was developed to provide very precise time coordination of LAN-connected computers. The daemon must run as root to manipulate the system clock and use low port numbers. The ptpd2 daemon is feature rich, supports IPv4 multicast, unicast and hybrid mode (mixed) operation, as well as Ethernet mode. Even without hardware assistance, ptpd2 is able to achieve and maintain millisecond level timing precision and is able to withstand PTP Grandmaster failovers, link failures, and restarts with minimal impact to timing performance. With hardware assistance, ptpd2 is able to achieve and maintain sub-microsecond level timing precision.

--key:section="value"

Enter ptpd2 -H to show detailed help for all settings.

Statistics log file:

When you enable the statistics log, a ptpd2 client (slave) logs clock synchronization information for every Sync and Delay Response message it receives. When ptpd2 starts up or flushes the log, a comment line (starting with #) that contains the names of all columns is logged. The format of this log is a series of comma-separated values (CSV) and it can be easily imported into statistics tools and most spreadsheet software packages for analysis and graphing.

This log can get very large when you run ptpd2 for longer periods of time and with high message rates. To reduce the number of messages logged, use global:statistics_log_interval to limit the log output to only one message per configured interval. You can also control the size and maximum number of the statistics log (for more information, enter ptpd2 -H).

Statistics log columns

Timestamp

The time when the message was received. The global:statistics_timestamp_format setting determines whether this value takes the form of text date and time, Unix timestamp (with fractional seconds), or both (adds an extra field). For more information, enter ptpd2 -H.

If you import the log into plotting software and the software can understand Unix time, it is best to set the timestamp format to Unix or both, as some software cannot properly deal with the fractional part of the second when it converts the date and time from text.

State

The port state. See Port states.

Clock ID

The port identifier of the current best server (master), as defined by IEEE 1588. This value is the local clock's ID if the local clock is the best server.

It is displayed as clock_id/port(host). The port value is the PTP clock port number, not to be confused with UDP ports. The clock_id value is an EUI-64 64-bit ID, which is usually converted from the 48-bit MAC address by inserting 0xfffe between the lower and upper half of the MAC address.

The ptpd2 daemon attempts to convert the clock ID back to the MAC address and look up the hostname from /etc/ethers (for more information, see the FreeBSD documentation for ethers at https://man.freebsd.org/cgi/man.cgi?query=ethers&sektion=5&manpath=FreeBSD+13.3-RELEASE+and+Ports). Populating the ethers file helps the administrator to recognise the servers by familiar hostnames.

One Way Delay

The current value of the one-way delay (or mean path delay) in seconds, calculated by ptpd2 in client (slave) state from the exchange of Delay Request and Delay Response messages.

If this value remains at zero, this usually means that no Delay Response messages are being received, likely due to a network issue.

Offset From Master

The current value of the offset from the server (master) in seconds. This value is the main output of the PTP engine in client (slave) state, which is the input of the clock servo for clock corrections. It is the value typically observed when estimating the client performance.

Slave to Master

The intermediate offset value, in seconds, extracted from the exchange of Delay Request and Delay Response messages and used for computing one-way delay. If the last value was rejected by a filter, the previous value is shown in the log. This value is also zero if no Delay Response messages are being received.

Master to Slave

The intermediate offset value, in seconds, extracted from the Sync messages and used for computing the offset from the server (master). If the last value was rejected by a filter, the previous value is shown in the log.

Observed Drift

The frequency difference between the client (slave) clock and the client (master) clock as measured by the integral accumulator of the clock control proportional integral (PI) servo model. This value becomes stable when the clock offset has stabilised, and can be used to detect clock stability.

Last Packet Received

The message was received last: either S for Sync and D for Delay Response. If a client (slave) logs no D entries, this means it's not receiving Delay Response messages, which could be a network issue.

One Way Delay Mean

The offset from server (master) mean computed over the last sampling window.

One Way Delay Std Dev

The one-way delay standard deviation computed over the last sampling window.

Offset From Master Mean

The offset from server (master) mean computed over the last sampling window.

Offset From Master Std Dev

The offset from server (master) standard deviation computed over the last sampling window.

Observed Drift Mean

The observed drift or local clock frequency adjustment mean computed over the last sampling window.

Observed Drift Std Dev

The observed drift or local clock frequency adjustment standard deviation computed over the last sampling window. The lower the value, the less aggressively the clock is being controlled and, therefore, the more stable it is.

raw delayMS

The raw (unfiltered) delayMS value, which is useful for evaluating outliers and filter performance.

raw delaySM

The raw (unfiltered) delaySM value, which is useful for evaluating outliers and filter performance.

All the statistical measures (mean and standard deviation) are only computed and displayed if ptpd2 was built without --disable-statistics. The duration of the sampling period is controlled by global:statistics_update_interval (for more information, enter ptpd2 -H).

Port states

init

Initializing

flt

Faulty

lstn_init

Listening (first time)

lstn_reset

Listening (after reset)

pass

Passive (not best server (master), not announcing)

uncl

Uncalibrated

slv

Client (slave)

pmst

Ready to enter the server (master) state

mst

Active server (master)

dsbl

Disabled

? (unk)

Unknown state

Signals:

Exit status:

0

Success. Either successfully started in daemon mode, or otherwise exited cleanly. 0 is also returned when -k or --check-config is used and the configuration was correct.

1

All error conditions other than those indicated by the other exit codes. Includes configuration errors, running ptpd2 in help mode or with no parameters, self shutdown, network startup errors, and attempting to run ptpd2 as non-root.

2

Memory allocation errors during startup.

3

Lock file errors and when ptpd2 could not be started as daemon.

Contributing authors:

Gael Mace (gael_mace@users.sourceforge.net), Alexandre Van Kempen, Steven Kreuzer (skreuzer@freebsd.org), George Neville-Neil (gnn@freebsd.org), and Wojciech Owczarek (wojciech@owczarek.co.uk)