ptpd Daemon

Purpose

Starts the Precision Time Protocol (1588-2008) daemon (ptpd).

Syntax

/usr/sbin/ptpd [ -? ] [ -h ] [ -H ] [ -e setting ] [ -k ] [ -v ] [ -O ] [ -L ] [ -A ] [ -s ] [ -m ] [ -M ] [ -y ] [ -E ] [ -P ] [ -a ] [ -n ] [ -C ] [ -V ] [ -c file ] [ -R dir ] [ -f file ] [ -S file ] [ -d domain_number ] [ -u IP_address ] [ -r number ] [ -l file ] [ -i dev ]

Description

The ptpd daemon implements the Precision Time Protocol (PTP) version 2 as defined by the IEEE 1588-2008 standard. PTP provides precise time coordination of LAN-connected computers. You must run this daemon with root authority to manipulate the system clock and use lower port numbers. The ptpd daemon supports IPv4 multicast, unicast, hybrid mode (mixed), and Ethernet mode operations. The ptpd daemon can achieve and maintain submicrosecond level timing precision, even without hardware assistance.

Configure the ptpd daemon by using the /etc/ptpd2.conf configuration file (default file). The short (-x) and long (--xxxxx) flags provide basic control over the daemon operation, and provide only the basic PTP protocol settings. Other settings can be displayed by the -h, -H, and -e flags.

The ptpd daemon can be started either from System Resource Controller (SRC) or from the command line.

Use the following SRC commands to manipulate the ptpd daemon:

startsrc
Starts a subsystem, group of subsystems, or a subserver.
stopsrc
Stops a subsystem, group of subsystems, or a subserver.
refresh
Causes a subsystem or group of subsystems to read the appropriate configuration file again.
lssrc
Gets the status of a subsystem, group of subsystems, or a subserver.
Note: The ptpd daemon does not support Network Time Protocol (NTP) and Simple Network Management Protocol (SNMP) related functions.
The ptpd daemon uses the following terms:
slave device
A system running the ptpd daemon that accepts commands from a master device and synchronizes its system time to match the associated boundary clock time.
master device
A device bound to a boundary clock that synchronizes time with a set of one or more PTP slave devices on the same network.
grandmaster device
A master device that has the best clock provided by the Best Master Clock algorithm. It synchronizes all of the other master devices (also known as the boundary clocks), which in turn update and synchronize all of the associated slave devices. The grandmaster clock is also known as best master clock or best clock.

Flags

Short flag Long flag Description
-a --delay-override Overrides delay request interval announced by master in worker state. This flag sets the ptpengine attribute to the following setting:
ptpengine:log_delayreq_override
-A --auto-lock Uses preset or port mode-specific lock-file names. This flag is useful when you run multiple instances of the ptpd daemon.
-c file --config-file file Specifies the path of the configuration file.
-C --foreground Specifies the command to run in foreground. This flag sets the global attribute as follows:
global:foreground=Y
Note: This option is ignored if the ptpd daemon is started from SRC.
-d domain_number --domain domain_number Specifies the PTP domain number to become part of. This flag sets the ptpengine attribute as follows:
ptpengine:domain
-D [DD] --debug Specifies the debug level. This flag sets the global attribute as follows:
global:debug_level
You can specify multiple instances to increase the debug level information. For example, the -D option specifies minimal debug information. The -DD option specifies detailed debug information. The -DDD option specifies maximum debug information.
-e setting --explain setting Shows help information for a single setting. This flag sets the section attribute as follows:
section:key
-E --e2e Specifies end-to-end delay detection. This flag sets the ptpengine attribute as follows:
ptpengine:delay_mechanism=E2E
-f file --log-file file Specifies the path of the log file. This flag sets the global attribute as follows:
global:logfile
-h --help Shows help screen.
-H --long-help Shows detailed help for all settings and behaviors.
-i dev --interface dev Specifies the interface to be used for ptpd implementation. For example, en0. This flag sets the ptpengine attribute as follows:
ptpengine:interface
-k --check-config Checks the PTP configuration and exits. Returns 0 if the configuration is correct.
-l file --lockfile file Specifies the path of lock-file. This flag sets the global attribute as follows:
global:lock_file
-L --ignore-lock Skips checking and locking the lock-file. This flag sets the global attribute as follows:
global:ignore_lock
-m --masterslave Specifies the full IEEE 1588 implementation: master, slave when not gandmaster (best master). This flag sets the ptpengine attribute as follows:
ptpengine:preset=masterslave
-M --masteronly Specifies master only mode: passive when not best GM. This flag sets the ptpengine attribute as follows:
ptpengine:preset=masteronly
-n --clock:no_adjust Specifies not to adjust the clock. This flag sets the clock attribute as follows:
clock:no_adjust
-O --default-config Shows default configuration and exits. The output can be used as a configuration file.
-p --print-lockfile Prints path of the lock-file and exits. This flag is useful for init scripts in combination with auto lock-files.
-P --p2p Specifies peer-to-peer delay detection. This flag sets the ptpengine attribute as follows
ptpengine:delay_mechanism=P2P
-r number --delay-interval number Specifies the interval of delay request message (log 2). This flag sets the ptpengine attribute as follows:
ptpengine:log_delayreq_interval
-R dir --lock-directory dir Specifies the directory to store lock-files. This flag sets the global attribute as follows:
global:lock_directory
-S file --statistics-file file Specifies the path of statistics file. This flag sets the global attribute as follows:
global:statistics_file
-s --slaveonly Turns on the slave-only mode. This flag sets the ptpengine attribute as follows:
ptpengine:preset=slaveonly
-u --unicast Specifies unicast mode (no unicast negotiation) and sends all messages to IP. This flag sets the ptpengine attribute as follows:
ptpengine:ip_mode=unicast + ptpengine:unicast_address
-v --version Prints the version string and exits.
-V --verbose Specifies the command to run in foreground and to log all the messages to the standard output. This flag sets the global attribute as follows:
global:verbose_foreground=Y
Note: This option is ignored if the ptpd daemon is started from SRC.
-y --hybrid Specifies hybrid mode: mixed multicast and unicast operation. Multicast for sync and announce, unicast for delay request and response. This flag sets the ptpengine attribute as follows:
ptpengine:ip_mode=hybrid

PTP daemon port states

The ptpd port can have the following states:

State Description
init Initializing
flt Faulty
lstn_init Listening (first time)
lstn_reset Listening (subsequent reset)
pass Passive (not best master, not announcing)
uncl Uncalibrated
slv Worker
pmst Pre-master
mst Master (active)
dsbl Disabled
? (unk) Unknown state

Statistics log file format

The following options are available when you enable the ptpd statistics log:
ptpengine:log_statistics
Updates the login information for each received PTP packet.
ptpengine:statistics_file
Specifies the location path of the statistics log file.
Note: This option enables statistics gathering.

When the statistics logging is enabled, a ptpd worker logs clock sync information when sync and delay response message are received. When the ptpd daemon starts up or flushes the log, a comment line (starting with #) is logged, containing the names of all columns. The log file is in the comma-separated values (CSV) format and can be easily imported into statistics tools and spreadsheet software packages for analysis and creating graphs. The size of the log files increases when you run the ptpd daemon for longer duration and with high message rates. Therefore, to reduce the number of messages logged, the global:statistics_log_interval setting can be used to limit the log output to one message per configured interval. The size and maximum number of the statistics log files can also be controlled.

The description of the columns in the statistics log file follows:

Timestamp
Time when the message was received. The date and time information are represented as text, UNIX time stamp (with fractional seconds), or both forms (in this case, an extra field is added), depending on the global:statistics_timestamp_format setting. When you import the log file to plotting software, if the software can understand UNIX time, set the time stamp format to unix or both, because some software do not interpret the fractional part of the second when it converts the date and time from text.
State
The state of the port. For more information about various port states, see PTP daemon port states.
Clock ID
Port identity of the current best master, as defined by IEEE 1588 standard. This ID is the local clock's ID if the local clock is the best master. This parameter is displayed as clock_id or port (host). Port is the PTP clock port number, not the User Datagram Protocol (UDP) port numbers. The clock ID is an Extended Unique Identifier (EUI)-64 64-bit ID, converted from the 48-bit MAC address, by inserting 0xfffe at the middle of the MAC address.
One-way delay
Current value of one-way delay (or mean-path delay) in seconds, calculated by the ptpd daemon that is in the worker state from the delay request and delay response message exchange.
Note: If this value remains at zero, it means that no delay response messages are being received, which might be because of a network issue.
Offset from master
Current offset value from master device in seconds. It is the main output of the PTP engine that is in the worker state. This value is the input for clock corrections in the clock servo algorithms. This value is typically measured when estimating the performance of the worker device.
Slave to master
Intermediate offset value (seconds) extracted from the delay request and delay response message exchange. This value is used for computing one-way delay. If the last value was rejected by a filter, the previous value is shown in the log file. This value is zero (0) if the delay response messages are not received.
Master to slave
Intermediate offset value (seconds) extracted from the sync messages. This value is used for computing the offset value from the master devices. If the last value was rejected by a filter, the previous value is shown in the log file.
Observed drift
The frequency difference between the worker clock and the master clock as measured by the integral accumulator of the clock control proportional integral (PI) servo model. This value stabilizes when the clock offset value is stabilized, and this value is used to detect clock stability.
Last packet received
This field shows which message was received last. It displays S for sync messages and D for delay response messages. If a worker device logs no D entries, it means that the worker device is not receiving delay response messages because of network issue.
One-way delay mean
One-way delay mean computed over the last sampling window.
One-way delay std dev
One-way delay standard deviation computed over the last sampling window.
Offset from master mean
Offset from master mean computed over the last sampling window.
Offset from master std dev
Offset from master standard deviation computed over the last sampling window.
Observed drift mean
Observed drift or local clock frequency adjustment mean computed over the last sampling window.
Observed drift std dev
Observed drift or local clock frequency adjustment standard deviation computed over the last sampling window. A lower value indicates that the clock is controlled less aggressively. Therefore, the value is more stable.
Note: All the statistical measures (mean and standard deviation) are computed and displayed only if the ptpd daemon was created by using the --enable-statistics flag. The duration of the sampling period is controlled with the global:statistics_update_interval setting.

Handling signals

The ptpd daemon handles the following signals:

Item Description
SIGHUP Reloads the configuration file (if used by the daemon) and reopens log files. The refresh subcommand of the SRC performs the same task.
SIGUSR1 When the subsystem is in the worker state, the ptpd daemon forces the clock to step to a current offset value from a master value.
SIGUSR2 Dumps all PTP protocol counters to current log target (and clears the counters if the ptpengine:sigusr2_clears_counters attribute is set).
SIGINT|SIGTERM Closes log files and other open files. It also cleans up lock file and exits.
SIGKILL Forces an unclean exit.

Exit status

Upon exit, the ptpd daemon returns 0 on success, either successfully started in daemon mode, or exited cleanly. The value of 0 is also returned when the -k (--check-config) option is used and the configuration was correct. A nonzero exit code is returned on errors. The value of 127 is returned if the ptpd daemon is started by a non-root user. The value of 3 is returned on lock-file errors and when the ptpd daemon cannot be started as daemon. The value of 2 is returned on memory allocation errors when the daemon is started. For all other error conditions such as configuration errors, running the ptpd daemon in help mode or without any parameters, self shutdown of subsystems, and network startup errors, the value of 1 is returned.

Examples

  1. To start the ptpd daemon with the SRC, enter the following command:
    startsrc -s ptpd
  2. To stop the ptpd daemon with the SRC, enter the following command:
    stopsrc -s ptpd
  3. To refresh the ptpd daemon with the SRC, enter the following command:
    refresh -s ptpd
    The ptpd daemon reloads the configuration file (if used by the daemon) and reopens log files.
  4. To check whether the configuration file in the /etc/ptpd2.conf path is configured correctly, enter the following command:
    ptpd -k
  5. To view the meaning of a single setting, enter the following command:
    ptpd -e ptpengine:interface
    The output explains the meaning of the ptpengine:interface setting.

Files

Item Description
/etc/ptpd2.conf Default path of the ptpd daemon configuration file.
/usr/samples/tcpip/ptpd2/ptpd2.conf Sample file of the ptpd2.conf configuration file.