ptpd2

ptpd2 [-?AaCDEgHhIKkLMmNnOPpsTUVvy] [-c path] [-d number] [-e setting]
     [-f path] [-l path] [-R directory] [-r number]
     [-S path] [-u  ip-address[,ip-address...]
     -i device

Runs on:

QNX Neutrino

Options:

Basic daemon and PTP protocol options

?

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

-A --auto-lock

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

-a --delay-override

In client (slave) mode, use the Delay Request message interval specified by -r or --delay-interval instead of the one announced by the server. To specify it in the configuration file, include log_delayreq_override.

-C --foreground

Prevents the daemon from running in the background. To specify it in the configuration file, include global:foreground=Y.

-c --config-file path

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

-D --debug

Specifies the debug level. Specify -D (minimal debug information), -DD (detailed information), or -DDD (maximum information). Only available if compiled with RUNTIME_DEBUG. To specify it in the configuration file, include global:debug_level.

-d --domain number

Specifies the PTP domain number to become part of. To specify it in the configuration file, include ptpengine:domain.

-E --e2e

Enables the end-to-end delay mechanism. To specify it in the configuration file, include ptpengine:delay_mechanism=E2E.

-e --explain setting

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

-f --log-file path

Specifies the log file path. To specify it in the configuration file, include global:logfile.

-g --unicast-negotiation

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 signalling message with announce interval set to -1. If this option is not specified, no signalling message is sent.

-i --interface device

Specifies the interface to use (e.g., eth0). To specify it in the configuration file, include ptpengine:interface.

-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

Skips lock file checks and locking. To specify this behavior in the configuration file, include global:ignore_lock.

-l --lockfile path

Specifies the lock file path. To specify it in the configuration file, include global:lock_file.

-M --masteronly

Specifies a clock that is always a server and is passive when a better server is available in the network. To specify it in the configuration file, include ptpengine:preset=masteronly.

-m --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. To specify it in the configuration file, include ptpengine:preset=masterslave.

-N --noswitch

Enables no-switch mode.

-n --clock:no_adjust

Prevents the clock from being adjusted. To specify it in the configuration file, include clock:no_adjust.

-O --default-config

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

-P --p2p

Enables the peer-to-peer delay mechanism. To specify it in the configuration file, include ptpengine:delay_mechanism=P2P.

-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).

-R --lock-directory directory

Specifies the directory to store lock files in. To specify it in the configuration file, include global:lock_directory.

-r --delay-interval number

Specifies the Delay Request message interval (log 2). To specify it in the configuration file, include ptpengine:log_delayreq_interval.

-S --statistics-file path

Specifies the statistics file path. To specify it in the configuration file, include global:statistics_file.

-s --slaveonly

Specifies a clock that is never a server. To specify it in the configuration file, include ptpengine:preset=slaveonly.

-T --dot2as

Enables 802.1AS support.

-U --unicast

Specifies unicast operation. To specify it in the configuration file, include ptpengine:ip_mode=unicast.

For server-only and hybrid operation, you must also specify unicast destinations (-u, --unicast-destinations, ptpengine:unicast_destinations) unless you specify unicast negotiation (-g, --unicast-negotiation, ptpengine:unicast_negotiation=y) for delay request and response.

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

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

Specifies unicast destinations. Requires -U or --unicast. To specify it in the configuration file, include ptpengine:ip_mode=unicast and ptpengine:unicast_destinations.

-V --verbose

Runs the daemon in the foreground and logs all messages to standard output. To specify it in the configuration file, include global:verbose_foreground=Y.

-v --version

Prints the version string and then ptpd2 exits.

-y --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

The ptpd2 daemon supports the following options that are compatible with versions before 2.3.0. They will be removed in a subsequent version. Until then, using them generates a warning:

-b device

Specifies the network interface to use.

-G

Specifies server-only (master-only) mode with NTP.

-g

Specifies client-only (slave-only) mode.

-i number

Specifies the PTP domain number.

-t

Prevents the clock from being adjusted.

-U

Specifies hybrid mode (mixed unicast and multicast operation).

-W

Specifies server or client (master or slave) mode without NTP.

-Y number

Specifies the Delay Request message interval (log 2).

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.

Because a configuration file is the preferred mechanism for configuring ptpd2, the options available as short (e.g., -c) and long options (e.g., --config-file) mostly provide basic control over the daemon operation, and only provide the very basic PTP protocol settings. The rest of the settings can also be specified as command-line options, but they use the following format:

--key:section="value"

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

Statistics log file:

The following settings enable the statistics log:

• -V, --verbose, global:verbose_foreground=Y
• ptpengine:log_statistics
• ptpengine:statistics_file (specifying the file enables statistics logging)

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/ethers/5). 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:

The ptpd2 daemon handles the following signals:

SIGHUP

Reload configuration file (if used) and reopen log files

SIGUSR1

When in client (slave) state, force clock step to current offset from server (master) value

SIGUSR2

Dump all PTP protocol counters to current log target (and clear if ptpengine:sigusr2_clears_counters is set)

SIGINT | SIGTERM

Clean exit: close logs and other open files, clean up lock file, and exit

SIGKILL

Force an unclean exit

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)