Scroll to navigation

ptpd2.conf(5) PTPd config file ptpd2.conf(5)

NAME

ptpd2.conf - Precision Time Protocol daemon config file

CONFIGURATION FILE FORMAT

Settings in the PTPd configuration file are grouped into sections and take the form of section:key="value" variables. The configuration file can either be formatted that way (preferred) or in .ini file style where a series of key="value" variables is grouped into sections using [section] headers. Every setting listed here can also be specified as a command line parameter (--section:key=value ). Quotation marks are optional. NOTE: the configuration file must end with a newline.

RELOADING CONFIGURATION

Only a small number of configuration file settings (SNMP, lock file configuration) requires PTPd restart to take effect. All other settings can be changed while ptpd is running - configuration file is reloaded and checked for changes when PTPd receives the SIGHUP signal. When reloading configuration, PTPd will always attempt to test settings before applying them and once running, will never exit as a result of configuration errors.

PRIORITY

Any setting passed as a command line parameter will always take priority over the configuration file, so once ptpd is running, those settings cannot be changed - a warning will be logged on every attempt to change those settings using the configuration file.

CONFIGURATION SECTIONS

ptpengine
PTP protocol specific configuration
clock
Clock related settings
servo
Clock control PI servo configuration
global
Global configuration - logging, etc.
ntpengine
NTP control configuration (if compiled with PTPD_NTPDC)

CONFIGURATION VARIABLES

ptpengine:interface [STRING]
usage
Network interface to use - eth0, igb0 etc. (required).
default
[none]
ptpengine:preset [SELECT]
options
none slaveonly masteronly masterslave
usage
PTP engine preset:
none
Defaults, no clock class restrictions
slaveonly
Slave only (clock class 255 only)
masteronly
Master, passive when not best master (clock class 0..127)
masterslave
Full IEEE 1588 implementation: Master, slave when not best master (clock class 128..254)
default
slaveonly
NOTE:
Presets affect the following settings: ptpengine:slave_only, clock_no_adjust and ptpengine:clock_class (range and default value). To see all preset settings, run ptpd2 -H (--long-help)
ptpengine:ip_mode [SELECT]
options
multicast unicast hybrid
usage
IP transmission mode (requires IP transport):
multicast
uses multicast for all messages
hybrid
uses multicast for sync and announce, and unicast for delay request and response
unicast
uses unicast for all transmission. When unicast mode is selected, destination IP must be configured ( ptpengine:unicast_address).
default
multicast
ptpengine:transport [SELECT]
options
ipv4 ethernet
usage
Transport type for PTP packets.
default
ipv4
ptpengine:use_libpcap [BOOLEAN]
usage
Use libpcap for sending and receiving traffic (automatically enabled in Ethernet mode).
default
N
ptpengine:delay_mechanism [SELECT]
options
E2E P2P DELAY_DISABLED
usage
Delay detection mode used - use DELAY_DISABLED for syntonisation only (no synchronisation).
default
E2E
ptpengine:domain [INT: 0 .. 127]
usage
PTP domain number.
default
0
ptpengine:slave_only [BOOLEAN]
usage
Slave only mode (sets clock class to 255, overriding value from preset).
default
Y
ptpengine:inbound_latency [INT]
usage
Specify latency correction (nanoseconds) for incoming packets.
default
0
ptpengine:outbound_latency [INT]
usage
Specify latency correction (nanoseconds) for outgoing packets.
default
0
ptpengine:offset_shift [INT]
usage
Apply an arbitrary shift (nanoseconds) to offset from master when in slave state. Value can be positive or negative - useful for correcting for of antenna latencies, delay assymetry and IP stack latencies. This will not be visible in the offset from master value - only in the resulting clock correction.
default
0
ptpengine:always_respect_utc_offset [BOOLEAN]
usage
Compatibility option: In slave state, always respect UTC offset announced by best master, even if the the
currrentUtcOffsetValid flag is announced FALSE. NOTE: this behaviour is not part of the standard.
default
N
ptpengine:prefer_utc_offset_valid [BOOLEAN]
usage
Compatibility extension to BMC algorithm: when enabled, BMC for both master and save clocks will prefer masters announcing currrentUtcOffsetValid as TRUE.
NOTE: this behaviour is not part of the standard.
default
N
ptpengine:require_utc_offset_valid [BOOLEAN]
usage
Compatibility option: when enabled, ptpd2 will ignore Announce messages from masters announcing currentUtcOffsetValid as FALSE. NOTE: this behaviour is not part of the standard.
default
N
ptpengine:log_announce_interval [INT: -1 .. 7]
usage
PTP announce message interval in master state.(expressed as log 2 i.e. -1=0.5s, 0=1s, 1=2s etc.)
default
1
ptpengine:announce_receipt_timeout [INT: 2 .. 255]
usage
PTP announce receipt timeout announced in master state.
default
6
ptpengine:announce_receipt_grace_period [INT: 0 .. 20]
usage
PTP announce receipt timeout grace period in slave state: when announce receipt timeout occurs, disqualify current best GM,
then wait n times announce receipt timeout before resetting. Allows for a seamless GM failover when standby GMs are slow
to react. When set to 0, this option is not used.
default
0
ptpengine:log_sync_interval [INT: -7 .. 7]
usage
PTP sync message interval in master state (expressed as log 2 i.e. -1=0.5s, 0=1s, 1=2s etc.)
default
0
ptpengine:log_delayreq_override [BOOLEAN]
usage
Override the Delay Request interval announced by best master.
default
N
ptpengine:log_delayreq_interval_initial [INT: -7 .. 7]
usage
Delay request interval used before receiving first delay response (expressed as log 2 i.e. -1=0.5s, 0=1s, 1=2s etc.)
default
0
ptpengine:log_delayreq_interval [INT: -7 .. 7]
usage
Minimum delay request interval announced when in master state, in slave state overrides the master interval, required in hybrid mode.
(expressed as log 2 i.e. -1=0.5s, 0=1s, 1=2s etc.)
default
0
ptpengine:log_peer_delayreq_interval [INT: -7 .. 7]
usage
Minimum peer delay request message interval in peer to peer delay mode (expressed as log 2 i.e. -1=0.5s, 0=1s, 1=2s etc.)
default
1
ptpengine:foreignrecord_capacity [INT: 5 .. 10]
usage
Foreign master record size (Maximum number of foreign masters).
default
5
ptpengine:ptp_allan_variance [INT: 0 .. 65535]
usage
Specify Allan variance announced in master state.
default
28768
ptpengine:ptp_clock_accuracy [SELECT]
options
ACC_25NS ACC_100NS ACC_250NS ACC_1US ACC_2.5US ACC_10US ACC_25US ACC_100US ACC_250US ACC_1MS ACC_2.5MS ACC_10MS ACC_25MS ACC_100MS ACC_250MS ACC_1S ACC_10S ACC_10SPLUS ACC_UNKNOWN
usage
Clock accuracy range announced in master state.
default
ACC_UNKNOWN
ptpengine:utc_offset [INT]
usage
Underlying time source UTC offset announced in master state.
default
0
ptpengine:utc_offset_valid [BOOLEAN]
usage
Underlying time source UTC offset validity announced in master state.
default
N
ptpengine:time_traceable [BOOLEAN]
usage
Underlying time source time traceability announced in master state.
default
N
ptpengine:frequency_traceable [BOOLEAN]
usage
Underlying time source frequency traceability announced in master state.
default
N
ptpengine:ptp_timescale [SELECT]
options
PTP ARB
usage
Time scale announced in master state (with ARB, UTC properties are ignored by slaves). When clock class is set to 13 (application specific), this value is ignored and ARB is used.
default
ARB
ptpengine:ptp_timesource [SELECT]
options
ATOMIC_CLOCK GPS TERRESTRIAL_RADIO PTP NTP HAND_SET OTHER INTERNAL_OSCILLATOR
usage
Time source announced in master state.
default
INTERNAL_OSCILLATOR
ptpengine:clock_class [INT: 0 .. 255]
usage
Clock class - announced in master state. Always 255 for slave-only. Minimum, maximum and default values are controlled by presets. If set to 13 (application specific time source), announced time scale is always set to ARB. This setting controls the states a PTP port can be in. If below 128, port will only be in MASTER or PASSIVE states (master only). If above 127, port will be in MASTER or SLAVE states.
default
255
ptpengine:priority1 [INT: 0 .. 248]
usage
Priority 1 announced in master state,used for Best Master Clock selection.
default
128
ptpengine:priority2 [INT: 0 .. 248]
usage
Priority 2 announced in master state, used for Best Master Clock selection.
default
128
ptpengine:unicast_address [STRING]
usage
Specify unicast destination for unicast master mode (in unicast slave mode, overrides delay request destination).
default
[none]
ptpengine:management_enable [BOOLEAN]
usage
Enable handling of PTP management messages.
default
Y
ptpengine:management_set_enable [BOOLEAN]
usage
Accept SET and COMMAND management messages.
default
N
ptpengine:igmp_refresh [BOOLEAN]
usage
Send explicit IGMP joins between engine resets and periodically in master state.
default
Y
ptpengine:master_igmp_refresh_interval [INT: 0 .. 255]
usage
Periodic IGMP join interval (seconds) in master state when running IPv4 multicast: when set below 10 or when ptpengine:igmp_refresh is disabled, this setting has no effect.
default
60
ptpengine:multicast_ttl [INT: 1 .. 64]
usage
Multicast time to live for multicast PTP packets (ignored and set to 1 for peer to peer messages).
default
64
ptpengine:ip_dscp [INT: 0 .. 63]
usage
DiffServ CodepPoint for packet prioritisation (decimal). When set to zero, this option is not used. Use 46 for Expedited Forwarding (0x2e).
default
0
ptpengine:delay_outlier_filter_enable [BOOLEAN]
usage
Enable outlier filter for the Delay Response component in slave state
default
N
ptpengine:delay_outlier_filter_action [SELECT]
options
discard filter
usage
Delay Response outlier filter action. If set to 'filter', outliers are replaced with moving average.
default
filter
ptpengine:delay_outlier_filter_capacity [INT: 4 .. 60]
usage
Number of samples in the Delay Response outlier filter buffer
default
20
ptpengine:delay_outlier_filter_threshold [FLOAT: 0.001000 .. 1000.000000]
usage
Delay Response outlier filter threshold: multiplier for Peirce's maximum standard deviation. When set below 1.0, filter is tighter, when set above 1.0, filter is looser than standard Peirce's test.
default
1.000000
ptpengine:delay_outlier_weight [FLOAT: 0.010000 .. 2.000000]
usage
Delay Response outlier weight: if an outlier is detected, determines the amount of its deviation from mean that is used to build the standard deviation statistics and influence further outlier detection. When set to 1.0, the outlier is used as is.
default
1.000000
ptpengine:sync_outlier_filter_enable [BOOLEAN]
usage
Enable outlier filter for the Sync component in slave state.
default
N
ptpengine:sync_outlier_filter_action [SELECT]
options
discard filter
usage
Sync outlier filter action. If set to 'filter', outliers are replaced with moving average.
default
filter
ptpengine:sync_outlier_filter_capacity [INT: 4 .. 60]
usage
Number of samples in the Sync outlier filter buffer.
default
20
ptpengine:sync_outlier_filter_threshold [FLOAT: 0.001000 .. 1000.000000]
usage
Sync outlier filter threshold: multiplier for the Peirce's maximum standard deviation. When set below 1.0, filter is tighter, when set above 1.0, filter is looser than standard Peirce's test.
default
1.000000
ptpengine:sync_outlier_weight [FLOAT: 0.010000 .. 2.000000]
usage
Sync outlier weight: if an outlier is detected, this value determines the amount of its deviation from mean that is used to build the standard deviation statistics and influence further outlier detection. When set to 1.0, the outlier is used as is.
default
1.000000
ptpengine:calibration_delay [INT: 0 .. 100]
usage
Delay between moving to slave state and enabling clock updates, expressed as number of statistics update periods (global:statistics_update_interval). This allows one-way delay to stabilise before starting clock updates. Activated when going into slave state and during slave's GM failover. 0 - not used.
default
0
ptpengine:panic_mode [BOOLEAN]
usage
Enable panic mode: when offset from master is above 1 second, stop updating the clock for a period of time and then step the clock if offset remains above 1 second.
default
N
ptpengine:panic_mode_duration [INT: 1 .. 60]
usage
Duration (minutes) of the panic mode period (no clock updates) when offset above 1 second detected.
default
2
ptpengine:panic_mode_exit_threshold [INT: 0 .. 999999999]
usage
Do not exit panic mode until offset drops below this value (nanoseconds). 0 = not used.
default
0
ptpengine:pid_as_clock_idendity [BOOLEAN]
usage
Use JobID (PID) for UUID.
default
N
ptpengine:ntp_failover [BOOLEAN]
usage
Fail over to NTP when PTP time sync not available - requires ntpengine:enabled, but does not require the rest of NTP configuration: will warn instead of failing over if cannot control ntpd.
default
N
ptpengine:ntp_failover_timeout [INT: 0 .. 1800]
usage
NTP failover timeout in seconds: time between PTP slave going into LISTENING state, and failing over to NTP. 0 = fail over immediately.
default
60
ptpengine:prefer_ntp [BOOLEAN]
usage
Prefer NTP time synchronisation when not controlling the clock (all states, including slave when clock:no_adjust set).
default
N
ptpengine:panic_mode_ntp [BOOLEAN]
usage
When entering panic mode, fail over to NTP (after the NTP failover timeout period) - requires ntpengine:enabled but does not require the rest of NTP configuration - will warn instead of failing over if it cannot control ntpd.
default
N
ptpengine:sigusr2_clears_counters [BOOLEAN]
usage
When compiled with --enable-sigusr2=counters, clear counters after dumping all counter values.
default
N
ptpengine:timing_acl_permit [STRING]
usage
Permit access control list for timing packets. Format is a series of comma-separated network prefixes in full CIDR notation a.b.c.d/x where a.b.c.d is the subnet and x is the mask. For single IP addresses, a /32 mask is required for the ACL to be parsed correctly. The match is performed on the source IP address of the incoming messages. IP access lists are only supported when using the IP transport.
default
[none]
ptpengine:timing_acl_deny [STRING]
usage
Deny access control list for timing packets. Format is a series of comma-separated network prefixes in full CIDR notation a.b.c.d/x where a.b.c.d is the subnet and x is the mask. For single IP addresses, a /32 mask is required for the ACL to be parsed correctly. The match is performed on the source IP address of the incoming messages. IP access lists are only supported when using the IP transport.
default
[none]
ptpengine:management_acl_permit [STRING]
usage
Permit access control list for management messages. Format is a series of comma-separated network prefixes in full CIDR notation a.b.c.d/x where a.b.c.d is the subnet and x is the mask. For single IP addresses, a /32 mask is required for the ACL to be parsed correctly. The match is performed on the source IP address of the incoming messages. IP access lists are only supported when using the IP transport.
default
[none]
ptpengine:management_acl_deny [STRING]
usage
Deny access control list for management messages. Format is a series of comma-separated network prefixes in full CIDR notation a.b.c.d/x where a.b.c.d is the subnet and x is the mask. For single IP addresses, a /32 mask is required for the ACL to be parsed correctly. The match is performed on the source IP address of the incoming messages. IP access lists are only supported when using the IP transport.
default
[none]
ptpengine:timing_acl_order [SELECT]
options
permit-deny deny-permit
usage
Order in which permit and deny access lists are evaluated for timing packets, the evaluation process is the same as for Apache httpd.
default
deny-permit
ptpengine:management_acl_order [SELECT]
options
permit-deny deny-permit
usage
Order in which permit and deny access lists are evaluated for management messages, the evaluation process is the same as for Apache httpd.
default
deny-permit
clock:no_adjust [BOOLEAN]
usage
Do not adjust the clock.
default
N
clock:no_reset [BOOLEAN]
usage
Do not reset the clock - only slew.
default
N
clock:set_rtc_on_step [BOOLEAN]
usage
Attempt setting the RTC when stepping clock (Linux only - FreeBSD does this for us. WARNING: this will always set the RTC to OS clock time, regardless of time zones, so this assumes that RTC runs in UTC - true at least on most single-boot x86 Linux systems.
default
N
clock:drift_handling [SELECT]
options
reset preserve file
usage
Observed drift handling method between servo restarts:
reset
set to zero (not recommended)
preserve
use kernel value
file
load/save to drift file on startup/shutdown, use kernel value inbetween. To specify drift file, use the clock:drift_file setting.
default
preserve
clock:drift_file [STRING]
usage
Specify drift file
default
/etc/ptpd2_kernelclock.drift
clock:max_offset_ppm [INT: 500 .. 1000]
usage
Maximum absolute frequency shift which can be applied to the clock servo when slewing the clock. Expressed in parts per million (1 ppm = shift of 1 us per second. Values above 512 will use the tick duration correction to allow even faster slewing. Default maximum is 512 without using tick.
default
500
servo:delayfilter_stiffness [INT]
usage
One-way delay filter stiffness.
default
6
servo:kp [FLOAT: min: 0.000001 ]
usage
Clock servo PI controller proportional component gain (kP).
default
0.100000
servo:ki [FLOAT: min: 0.000001 ]
usage
Clock servo PI controller integral component gain (kI).
default
0.001000
servo:dt_method [SELECT]
options
none constant measured
usage
How servo update interval (delta t) is calculated:
none
servo not corrected for update interval (dt always 1),
constant
constant value (target servo update rate - sync interval for PTP,
measured
servo measures how often it's updated and uses this interval.
default
constant
servo:stability_detection [BOOLEAN]
usage
Enable clock synchronisation servo stability detection (based on standard deviation of the observed drift value) - drift will be saved to drift file / cached when considered stable, also clock stability status will be logged.
default
N
servo:stability_threshold [FLOAT: 1.000000 .. 10000.000000]
usage
Specify the observed drift standard deviation threshold in parts per billion (ppb) - if stanard deviation is within the threshold, servo is considered stable.
default
5.000000
servo:stability_period [INT: 1 .. 100]
usage
Specify for how many statistics update intervals the observed drift standard deviation has to stay within threshold to be considered stable.
default
3
servo:stability_timeout [INT: 1 .. 60]
usage
Specify after how many minutes without stabilisation servo is considered unstable. Assists with logging servo stability information and allows to preserve observed drift if servo cannot stabilise.
default
10
servo:max_delay [INT: 0 .. 999999999]
usage
Do not update one-way delay if slave to master delay (delaySM from Delay Response) is greater than this value (nanoseconds). 0 = not used.
default
0
servo:max_offset [INT: 0 .. 999999999]
usage
Do not reset the clock if offset from master is greater than this value (nanoseconds). 0 = not used.
default
0
global:enable_snmp [BOOLEAN]
usage
Enable SNMP agent (if compiled with PTPD_SNMP).
default
N
global:use_syslog [BOOLEAN]
usage
Send log messages to syslog. Disabling this sends all messages to stdout (or speficied log file).
default
N
global:lock_file [STRING]
usage
Lock file location
default
[none]
global:auto_lockfile [BOOLEAN]
usage
Use mode specific and interface specific lock file (overrides global:lock_file).
default
N
global:lock_directory [STRING]
usage
Lock file directory: used with automatic mode-specific lock files, also used when no lock file is specified. When lock file is specified, it's expected to be an absolute path.
default
/var/run
global:ignore_lock [BOOLEAN]
usage
Skip lock file checking and locking.
default
N
global:quality_file [STRING]
usage
File used to record data about sync packets. Enables recording when set.
default
[none]
global:quality_file_max_size [INT: min: 0 ]
usage
Maximum sync packet record file size (in kB) - file will be truncated if size exceeds the limit. 0 - no limit.
default
0
global:quality_file_max_files [INT: 0 .. 100]
usage
Enable log rotation of the sync packet record file up to n files. 0 - do not rotate.
default
0
global:quality_file_truncate [BOOLEAN]
usage
Truncate the sync packet record file every time it is (re) opened: startup and SIGHUP.
default
N
global:status_file [STRING]
usage
File used to log ptpd2 status information.
default
/var/run/ptpd2.status
global:log_status [BOOLEAN]
usage
Enable / disable writing status information to file.
default
N
global:status_update_interval [INT: 1 .. 30]
usage
Status file update interval in seconds.
default
1
global:log_file [STRING]
usage
Specify log file path (event log). Setting this enables logging to file.
default
[none]
global:log_file_max_size [INT: min: 0 ]
usage
Maximum log file size (in kB) - log file will be truncated if size exceeds the limit. 0 - no limit.
default
0
global:log_file_max_files [INT: 0 .. 100]
usage
Enable log rotation of the sync packet record file up to n files. 0 - do not rotate.
default
0
global:log_file_truncate [BOOLEAN]
usage
Truncate the log file every time it is (re) opened: startup and SIGHUP.
default
N
global:log_level [SELECT]
options
LOG_ERR LOG_WARNING LOG_NOTICE LOG_INFO LOG_ALL
usage
Specify log level (only messages at this priority or higer will be logged). The minimal level is LOG_ERR. LOG_ALL enables debug output if compiled with RUNTIME_DEBUG.
default
LOG_ALL
global:statistics_file [STRING]
usage
Specify statistics log file path. Setting this enables logging of statistics, but can be overriden with global:log_statistics.
default
[none]
global:statistics_log_interval [INT: min: 0 ]
usage
Log timing statistics every n seconds for Sync and Delay messages (0 - log all).
default
0
global:statistics_file_max_size [INT: min: 0 ]
usage
Maximum statistics log file size (in kB) - log file will be truncated if size exceeds the limit. 0 - no limit.
default
0
global:statistics_file_max_files [INT: 0 .. 100]
usage
Enable log rotation of the statistics file up to n files. 0 - do not rotate.
default
0
global:statistics_file_truncate [BOOLEAN]
usage
Truncate the statistics file every time it is (re) opened: startup and SIGHUP.
default
N
global:dump_packets [BOOLEAN]
usage
Dump the contents of every PTP packet
default
N
global:verbose_foreground [BOOLEAN]
usage
Run in foreground with statistics and all messages logged to stdout. Overrides log file and statistics file settings and disables syslog.
default
N
global:foreground [BOOLEAN]
usage
Run in foreground - ignored when global:verbose_foreground is set
default
N
global:log_statistics [BOOLEAN]
usage
Log timing statistics for every PTP packet received
default
N
global:cpuaffinity_cpucore [INT: -1 .. 255]
usage
Bind ptpd2 process to a selected CPU core number. 0 = first CPU core, etc. -1 = do not bind to a single core.
default
0
global:statistics_update_interval [INT: 1 .. 60]
usage
Clock synchronisation statistics update interval in seconds
default
5
ntpengine:enabled [BOOLEAN]
usage
Enable NTPd integration
default
N
ntpengine:control_enabled [BOOLEAN]
usage
Enable control over local NTPd daemon
default
N
ntpengine:check_interval [INT: 5 .. 600]
usage
NTP control check interval in seconds
default
15
ntpengine:key_id [INT: 0 .. 65535]
usage
NTP key number - must be configured as a trusted control key in ntp.conf, and be non-zero for the ntpengine:control_enabled setting to take effect.
default
0
ntpengine:key [STRING]
usage
NTP key (plain text, max. 20 characters) - must match the key configured in ntpd's keys file, and must be non-zero for the ntpengine:control_enabled setting to take effect.
default
[none]

BUGS

Configuration file support has only been introduced in version 2.3. There may still be some inconsistencies in the way some settings are parsed and while order should not make any difference, for some complex behaviours it may still be the case. Please report any bugs using the bug tracker on the SourceForge page: http://sourceforge.net/projects/ptpd/

SEE ALSO

ptpd2(8)

AUTHORS

Steven Kreuzer <skreuzer@freebsd.org>
Gael Mace <gael_mace@users.sourceforge.net>
George Neville-Neil <gnn@freebsd.org>
Wojciech Owczarek <wojciech@owczarek.co.uk>
Alexandre Van Kempen
ptpd2.conf(5) man page written by Wojciech Owczarek for ptpd 2.3.0 in November 2013
November, 2013 version 2.3.0