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 slave 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`	Slave
`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 slave 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 slave 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 slave 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 slave 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 slave 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 slave device logs no D entries, it means that the slave 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 slave 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

To start the ptpd daemon with the SRC, enter the following command:
```
startsrc -s ptpd
```
To stop the ptpd daemon with the SRC, enter the following command:
```
stopsrc -s ptpd
```
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.
To check whether the configuration file in the /etc/ptpd2.conf path is configured correctly, enter the following command:
```
ptpd -k
```
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.