Configuration
This section details all of the options supported by TimeKeeper. These options are all stored in the following file:
Linux:
/etc/timekeeper.conf
Windows:
%ProgramFiles%\timekeeper\timekeeper.conf
TimeKeeper’s configuration file is made of simple shell statements and functions. On
Unix based systems the configuration file must be readable by the “nobody” user.
Time sources are identified with the syntax:
SOURCE0() {
# Source configuration parameters
}
The number following the SOURCE function name, 0 here, indicates the priority of the source.
PTP servers are identified similarly:
SERVEPTP0() {
# PTP server configuration parameters
}
PTP servers are numbered to differentiate between different servers on different domains, interfaces, etc., but are not priority based like the sources are above.
Compliance report definitions also follow this same form:
COMPLIANCEREPORT0() {
# Compliance report configuration parameters
}
Following the shell conventions, capitalization is important, so all functions and variables must be capitalized in order for TimeKeeper to detect them. Any detected errors in the configuration file will be logged in the timekeeper log in ${LOGDIR} during startup.
Individual configuration options relevant to each scenario are discussed below. In the Values column, “N, M” means the option can be set to either N or M, “N - M” means the option can be set to values from N to M, inclusive, and “N -” means the same as “N - M” but there is no maximum value.
Global options
Below are global settings for TimeKeeper. For settings that take an input of 0 or 1, 0 turns the feature off and 1 turns the feature on. In general, TimeKeeper will apply default values, and there is no need to explicitly configure these settings unless there is a need for a specific feature.
| Option | Values | Units | Default | Example | Description |
|---|---|---|---|---|---|
| ALLOW_SET_TIME_AFTER_STARTUP | 0, 1 | NA | 0 | 1 | Allow TimeKeeper to set the time (perform a step) if the time offset is found to be large after becoming active. When a step is needed, TimeKeeper emits a syslog/SNMP trap event indicating the event occurred. |
| AVOID_IFACES | text | NA | NA | ‘eth4,eth5’ | A comma separated list of interface names that TimeKeeper will avoid enabling features on, like timestamping capabilities. |
| CPU | -1 - | NA | (see Description) | 0 | The CPU number that TimeKeeper should put all processes and threads on. A value of -1 will prevent TimeKeeper from applying affinities. If left unspecified, TimeKeeper will choose the last CPU on Linux. |
| DONOTROTATELOGSONSTARTUP | 0, 1 | NA | 0 | 1 | Prevent TimeKeeper from rotating logs on startup. |
| DISABLE_CLOCK_STEER | 0, 1 | NA | 0 | 1 | A value of 1 prevents TimeKeeper from steering clocks, including the system clock. It will also prevent TimeKeeper from disabling other timing daemons at startup. This allows TimeKeeper to monitor another time daemon. Setting this value to 1 will prevent TimeKeeper from steering the clock and can result in accuracy issues. |
| EMAILNOTIFICATION | text | NA | NA | ‘jsmith@example.com’ | A comma separated list of email addresses to send alerts to. |
| EMAILNOTIFICATION_THROTTLE | 0 - 7200 | seconds | 0 | 300 | Used with EMAILNOTIFICATION. If set, when an event occurs an initial email will be sent. Other emails that would be sent between then and the throttle timeout value will be queued. Once the throttle timeout expires, any queued messages will be delivered as a single bundled email. |
| ENABLE_COMPLIANCE | 0, 1 | NA | 0 | 1 | A value of 1 will enable the Compliance package. |
| ENABLE_COMPLIANCE_DNS | 0, 1 | NA | 1 | 1 | A value of 1 will enable the Compliance module to resolve IP addresses to hostnames. |
| ENABLE_COMPLIANCE _GLOBAL_REPORT |
0, 1 | NA | 1 | 1 | A value of 1 will enable the Compliance report that covers all clients found. |
| ENABLE_FILESYNC_QUERY | 0, 1 | NA | 0 | 1 | A value of 1 enables queries for the newer Filesync log transfer method if the global ENABLE_MANAGEMENT_QUERY is on as well. |
| ENABLE_FILESYNC_RESPONSE | 0, 1 | NA | 0 | 1 | A value of 1 enables responses to the newer Filesync log transfer method responses if the global ENABLE_MANAGEMENT_RESPONSE is on as well. |
| ENABLE_HWTSTAMPS | 0, 1 | NA | 1 | 1 | TimeKeeper enables hardware timestamping by default, and in rare cases this triggers issues with buggy drivers and firmware. Setting this value to 0 will prevent TimeKeeper from trying to enable hardware timestamping at all. |
| ENABLE_INACTIVE_SOURCE_ALERT | 0, 1 | NA | 0 | 1 | A value of 1 enables TimeKeeper to send alerts when a source is inactive and does not respond within the outage time limit. Alerts for an inactive source are sent once every 3 minutes. |
| ENABLE_MANAGEMENT_QUERY | 0, 1 | NA | (see Description) | 1 | A value of 1 enables the system to query PTP systems for their time sync quality data, which is then stored on the querying system. Individual PTP sources and servers may enable or disable queries independently if this global option is enabled. If disabled it disables queries on all PTP sources and servers. The option defaults to 1 if allowed by the license and TimeKeeper is configured to serve NTP or PTP. |
| ENABLE_MANAGEMENT_RESPONSE | 0, 1 | NA | 1 | 1 | A value of 1 allows the system to respond to incoming PTP management data requests. Individual PTP sources and servers may enable or disable the ability to respond independently if this global option is enabled. If disabled it disables responses on all PTP sources and servers. The option defaults to 1 if allowed by the license and PTP is configured. |
| ENABLE_MAP | 0, 1 | NA | 1 | 1 | A value of 1 enables the collection of information needed to build a map of the timing network. |
| INFLUXDB_IPADDR | 0.0.0.0 - 255.255.255.255 |
NA | (see Description) | 10.10.10.1 | To enable InfluxDB streaming, enter the IP address for your external InfluxDB v1 HTTP API. TLS must be enabled (either a trusted or self-signed certificate will work). If undefined, streaming is disabled. |
| INFLUXDB_PORT | 1 - 65535 | NA | 8086 | 8086 | Enter the TCP port to connect to your external InfluxDB v1 HTTP API. TLS must be enabled (either a trusted or self-signed certificate will work). Defaults to 8086. |
| INFLUXDB_DATABASE | text | NA | timekeeper_db | timekeeper_db | Enter the name of the InfluxDB database. Defaults to timekeeper_db. |
| INFLUXDB_USERNAME | text | NA | NA | timekeeper | Enter the InfluxDB authentication username. If undefined, authentication is disabled. |
| INFLUXDB_PASSWORD | text | NA | NA | ‘/FdfibQTiP5RvBTxF+q6SA==’ | A string containing the encrypted password for InfluxDB authentication. The passphrase should be encoded with the encodepassphrase tool provided with TimeKeeper. If undefined, authentication is disabled. |
| ENABLE_NIC_BLACKLIST | 0, 1 | NA | 1 | 1 | A value of 1 allows TimeKeeper to avoid enabling features on interfaces with drivers that are known to be unstable. When applied TimeKeeper will use the interface as it would normally, but without all hardware specific features enabled. Disabling ENABLE_NIC_BLACKLIST will allow TimeKeeper to enable features even if the driver and version are known to be unstable. |
| ENABLE_NTP_FOLLOWUP | 0, 1 | NA | 1 | 1 | A value of 1 will cause the TimeKeeper NTP server (if enabled) to also respond to NTP requests with a followup NTP packet. On TimeKeeper clients, this allows processing of the followup to improve timing accuracy. |
| SERVENTP_ENABLE_NTPD_POLLINT | 0, 1 | NA | 0 | 1 | A value of 1 will cause the TimeKeeper NTP server (if enabled) to set the polling-interval field in server messages to satisfy ntpd clients since version 4.2.8p16. |
| ENABLE_PREFILESYNC _MANAGEMENT_RESPONSE |
0, 1 | NA | 1 | 1 | A value of 1 enables responses to queries from the management data transfer method that preceded Filesync. This should be disabled when all client data transfer is intended to be done with Filesync. |
| ENABLE_SATELLITEDATA | 0, 1 | NA | 1 | 1 | A value of 1 enables the collection of detailed GPS satellite angle/strength data if the GPS device supports it. |
| ENABLE_SFC_UUID_FILTER | 0, 1 | NA | 1 | 1 | When tracking PTP with a hardware timestamping Solarflare card, a value of 1 will configure the card to only provide hardware timestamps for PTP traffic that matches the UUID of the highest priority PTP source. |
| ENABLE_TKGPS_DETAIL | 0, 1 | NA | 1 | 1 | A value of 1 enables the collection of detailed GPS state with a TimeKeeper GPS device, if present - such as on a TimeKeeper grandmaster. |
| ENABLE_WEB_MANAGEMENT | 0, 1 | NA | 0 | 1 | A value of 1 enables the web management tools on the server. |
| FILESYNC_END_TIME | 00:00:00 - 24:00:00 |
NA | 24:00:00 | 09:00:00 | A text field formatted as ‘HH:MM:SS’ (hours, minutes, seconds) offset from UTC midnight indicating when the Filesync method of transferring client log files between servers and clients is required to end globally. This value can be overridden in specific sources' or servers' configurations, the default value ‘00:00:00’ is equivalent to ‘24:00:00’, that is, the end of the day. |
| FILESYNC_EXCLUDE | text | NA | NA | ‘192.168.*’ | A text field determining which Filesync clients/directories are NOT shared by the system using standard file glob patterns (*, ?, [], and !). This field defaults to allowing all clients/directories to be synchronized with a remote system. See the advanced networking section of the TimeKeeper manual for more information. |
| FILESYNC_INCLUDE | text | NA | * | ‘???.?[1-7].12.*’ | A text field determining which Filesync clients/directories are shared by a system using standard file glob patterns (*, ?, [], and !). Inclusion takes priority over exclusion. This field defaults to allowing all clients/directories to be synchronized with a remote system. See the advanced networking section of the TimeKeeper manual for more information. |
| FILESYNC_START_TIME | 00:00:00 - 24:00:00 |
NA | 00:00:00 | 08:00:00 | A text field formatted as ‘HH:MM:SS’ (hours, minutes, seconds) offset from UTC midnight indicating when the Filesync method of transferring client log files between servers and clients is allowed to start globally. This value can be overridden in specific sources' or servers' configurations. Together with ‘FILESYNC_END_TIME’ it defines a range during which transfers may occur. |
| HTTPS_KEY_PASSPHRASE | text | NA | NA | ‘HlrkiGkXEvI7Hkl 0wGOuzw==’ |
A string containing the encrypted password to be used to access a password-protected private key when enabling HTTPS support. The passphrase should be encoded with the encodepassphrase tool provided with TimeKeeper. |
| INACTIVE_CLIENT_THRESHOLD | 0 - | seconds | 0 | 100 | Specifies how long a client should be inactive before an alarm is triggered. (e.g., INACTIVE_CLIENT_THRESHOLD=600 sends alarms if any client inactivity exceeds 10 minutes). A value of 0 disables the alarm. |
| INITIAL_SERVE_ACCURACY | 0.0 - | seconds | 0.0 | 0.00001 | Accuracy required before serving time via NTP/PTP/TIME protocols after startup. |
| IPTOS | 0 - 255 | NA | 16 | 56 | The default server IP ToS value as an integer. For conversion to DSCP, use standard conversions. This has no effect on Windows. |
| LOGDIR | text | NA | (see Description) | ‘/var/log/timekeeper/’ | A string naming the directory where TimeKeeper logs will be stored. On non-Grandmaster Linux hosts the default is /var/log. On Windows the default is %ProgramFiles%\timekeeper\var\log. The string must be a full path without spaces. To use the Windows default location, do not configure this parameter. |
| MANAGEMENT_QUERY_INTERVAL | 15.0 - 3600.0 | seconds | 60.0 | 15.0 | Indicates how frequently to query PTP clients for their time sync quality data. |
| NTPSYNCERRORTHRESHOLD | 0.0 - | seconds | 0.0 | 0.000010 | If management queries and SNMP traps or email alerts are enabled, any NTP clients reporting a sync exceeding this threshold will cause an alarm to be triggered. (e.g., NTPSYNCERRORTHRESHOLD=0.000010 sends alarms if any client sync quality exceeds +-10us). A threshold violation will only be reported after the error has been seen to be below the threshold first. A special value of 0 disables the alarm and is the default. |
| SERVENTP | 0, 1 | NA | 0 | 1 | A value of 1 will cause TimeKeeper to respond to NTP requests on all interfaces. |
| SERVENTP_ENABLE _MANAGEMENT_QUERY |
0, 1 | NA | 1 | 1 | A value of 1 allows collection of self-reported accuracy information from clients via NTP. TimeKeeper must also be configured to send management queries. Note that if the client is TimeKeeper and can communicate via PTP, the NTP data will be superseded with the more complete details via PTP. |
| SERVENTP_IFACE | text | NA | NA | ‘eth4’ | A string naming the network interface that TimeKeeper should respond to NTP queries on. If TimeKeeper receives a request via that named interface, it will respond, but only on that interface. If the value of this setting is empty, TimeKeeper listens and responds on all interfaces. |
| SERVENTP_NTPKEYIDS | 1 - 65535 | NA | NA | 1,3,10 | A comma separated list of MD5 key IDs read from /etc/ntp/keys (on Windows, %ProgramData%\timekeeper\ntp.keys) used to authenticate client requests. |
| SERVETIME | 0, 1 | NA | 0 | 1 | A value of 1 will cause TimeKeeper to respond to time requests (RFC 868) on all interfaces. |
| SET_TIME_ON_STARTUP | 0, 1 | NA | 0 | 1 | A value of 1 forcibly sets the time on startup regardless of offset, rather than trying to slew, for a faster sync on startup. A value of 0 will allow the TimeKeeper to slew in as long as the offset is less than +/-5 seconds from the primary time source unless SET_TIME_THRESHOLD is used to set a different value. |
| SET_TIME_THRESHOLD | 0.01 - | seconds | 5.0 | 0.5 | Specifies the initial offset threshold allowed before a step is taken on startup, and also the threshold to allow an immediate correction post-startup if ALLOW_SET_TIME_AFTER_STARTUP is set. Default value is 5 seconds. This is useful in virtual environments where VM processing delays can cause the clock to have a large offset and need a near immediate rather than slow correction once the offset is confirmed. Minimum value is 10 milliseconds (0.01). Some environments may require a higher minimum value in practice. |
| SNMPTRAPEID | text | NA | (see Description) | “1234” | The SNMPv3-specific engine ID. For example, a value of “1234” results in “8000A6ED0431323334”. If not set, TimeKeeper will base it on the MAC address of the default network interface. |
| SNMPTRAPHOST | text | NA | NA | 10.10.0.12,10.0.0.12 | A comma separated list of SNMP servers to send traps to. |
| SNMPTRAPOID | text | NA | 1.3.6.1.4.1.42733.0 | 1.2.3.4 | An OID string to use for sending all SNMP trap messages. If left unspecified, TimeKeeper will deliver traps as specified in the TimeKeeper MIB. This is a legacy configuration option. |
| SNMPTRAPPASSPHRASE | text | NA | NA | ‘b5xNNXVAnOalxvq Tz8o35A==’ |
An encrypted passphrase to be used with SNMPv3 traps. |
| SNMPTRAPUSERNAME | text | NA | NA | timekeeper | A username to be used with SNMPv3 traps. |
| SOURCECHECK | 0, 1 | NA | 0 | 1 | A value of 1 will enable timing source cross checks described elsewhere in this document. |
| SOURCECHECK_AUTOVALIDATE _THRESHOLD |
0.0 - | seconds | 0.00003 | 0.001 | Sources must agree to within this value for the Sourcecheck feature to allow source validation. |
| SPECTRACOM_DRIVER_PATH | text | NA | NA | ‘/tmp/spectracomtsync/’ | A string naming the directory where the driver for a TSync card resides, if TimeKeeper intends to use a TSync card at runtime. |
| STEP_ON_LEAPSECOND | 0, 1 | NA | 0 | 1 | A value of 1 corrects leap seconds with an immediate clock jump instead of a slew. |
| SYMMETRICOM_DRIVER_PATH | text | NA | NA | ‘/opt/bc637_driv_rel’ | A string naming the directory where the driver for a BC637 card resides if TimeKeeper intends to use a BC637 card at runtime. This is the path to the directory that contains the drvr/ and samples/ directories, not the drvr/ directory itself. |
| SYNC_ERROR_THRESHOLD _ALERT_ONLY_PRIMARY |
0, 1 | NA | 0 | 1 | A value of 1 enables TimeKeeper to send sync error threshold alerts only for the primary source. By default alerts are sent for all sources that exceed the sync error threshold. |
| SYNC_ERROR_THRESHOLD _THROTTLE |
0 - 3600 | seconds | 5 | 3600 | Throttles the rate that TimeKeeper will send alerts about sync error threshold values being exceeded. The default prevents TimeKeeper from sending alerts more often than every 5 seconds. |
| TLS_VERSION | 1.2, 1.3 | NA | (see Description) | 1.2 | Specifies TLS version to use. Specify ‘1.2’ to use TLS version 1.2 and limit ciphers in use for the TimeKeeper GUI, or ‘1.3’ to use TLS version 1.3. The default is to not limit TLS versions in use. ‘1.3’ will only appear on devices that support TLS version 1.3. |
| VERBOSE_BMC | 0, 1 | NA | 0 | 1 | A value of 1 enables verbose logging of any BMC algorithm activity when handling PTP data. |
| VERBOSE_COMPLIANCE | 0, 1 | NA | 1 | 1 | A value of 1 enables verbose logging of Compliance-related activity. |
| VERBOSE_MANAGEMENT | 0, 1 | NA | 0 | 1 | A value of 1 enables verbose logging of management message behavior. |
| VERBOSE_MAP | 0, 1 | NA | 0 | 1 | A value of 1 enables verbose logging of timing map operations. |
| VERBOSE_NMEA | 0, 1 | NA | 0 | 1 | A value of 1 enables verbose logging of NMEA handling. |
| VERBOSE_NTP | 0, 1 | NA | 0 | 1 | A value of 1 enables verbose logging of NTP behavior. |
| VERBOSE_PPS | 0, 1 | NA | 0 | 1 | A value of 1 enables verbose logging of PPS-based configurations. |
| VERBOSE_PTP | 0, 1 | NA | 0 | 1 | A value of 1 enables verbose logging of PTP behavior. |
| VERBOSE_SERVER | 0, 1 | NA | 0 | 1 | A value of 1 enables verbose logging of TimeKeeper server actions. |
| VERBOSE_SOCKET | 0, 1 | NA | 0 | 1 | A value of 1 enables verbose logging of socket-related activity. |
| VERBOSE_TCPDUMP | 0, 1 | NA | 0 | 1 | A value of 1 enables tcpdump recording of PTP and NTP, kept alongside other TimeKeeper logs. |
| VERBOSE_TIMESTAMPS | 0, 1 | NA | 0 | 1 | A value of 1 enables verbose logging of timestamping activity. |
| WEB_MANAGEMENT_IP | 0.0.0.0 - 255.255.255.255 |
NA | 0.0.0.0 | 10.10.10.1 | An IP address that will restrict serving web data to clients accessing the machine via that IP. The default is to listen on all IPs. |
| WEB_MANAGEMENT_PORT | -1 - 65535 | NA | -1 | 8082 | What port the web management should run on. HTTP defaults to off (WEB_MANAGEMENT_PORT=-1) and can be enabled by specifying a port value. |
| WEB_MANAGEMENT_TIMEOUT | 5 - | minutes | 44640 | 1440 | How long before a web interface session is automatically logged out (idle or not). |
| ENABLE_PAM_AUTH | 0, 1 | NA | 0 | 1 | A value of 1 enables the web management to authenticate with the PAM user name and password from the Linux host. ENABLE_PAM_AUTH is only supported on Linux. |
| WINROTATECOUNT | -1 - | days | 7 | 10 | Sets the amount of TimeKeeper logs to retain on Windows. A value of -1 prevents TimeKeeper from ever rotating logs. |
Per source options
Examples of sources include an NTP server, a PTP grandmaster, or a local bus card. Each option will have different configuration directives.
NTP source options
| Option | Values | Units | Default | Example | Description |
|---|---|---|---|---|---|
| ENABLE_DETECT_ASYMMETRY | 0, 1 | NA | 0 | 1 | Will detect, measure, and notify the user of network link asymmetries. |
| ENABLE_RERESOLVE | 0, 1 | NA | 0 | 1 | A value of 1 will cause the source to periodically re-resolve the DNS name specified for the NTP source. |
| NTPKEYID | 1 - 65535 | NA | NA | 5 | Causes TimeKeeper to read /etc/ntp/keys (on Windows, %ProgramData%\timekeeper\ntp.keys) for a matching MD5 Key ID to use for authentication with the NTP server. |
| NTPSERVER | text | NA | NA | ‘ab-1.example.net’ | The IP address or DNS name of the intended NTP server. |
| NTPSYNCRATE | 0.015625 - 128 | pps | 0.9 | 1.0 | The rate at which to make NTP requests, X queries every second. NTPSYNCRATE=0.5 causes TimeKeeper to query the NTP server every 2 seconds. |
PTP source options
| Option | Values | Units | Default | Example | Description |
|---|---|---|---|---|---|
| ALLOW_DROPPED_FOLLOWUP | 0, 1 | NA | 0 | 1 | A value of 0 means a PTP grandmaster that promises a followup message must deliver one in order for this source to use a given time update. If set to 1, a failed followup delivery won’t prevent the sample from being updated. The default is recommended in nearly all deployments, as missing followups indicate a problem with PTP delivery or the grandmaster. |
| ALLOW_UNREASONABLE_UTC | 0, 1 | NA | 0 | 1 | Forces TimeKeeper to accept sync messages having UTC offsets not known to be correct. |
| ENABLE_CORRECTION | 0, 1 | NA | 1 | 1 | A value of 0 means this source will not make use of any transparent clock information provided in the PTP data, otherwise it will apply the correction to the timing data. |
| ENABLE_DETECT_ASYMMETRY | 0, 1 | NA | 0 | 1 | When configured properly, will detect, measure, and notify the user of network link asymmetries. |
| ENABLE_FILESYNC_QUERY | 0, 1 | NA | (see Description) | 1 | A value of 1 causes TimeKeeper to query clients for management data using the newer Filesync log transfer method on this source. Defaults to global option. TimeKeeper sends Filesync queries if both source and global options are enabled and this source is enabled to send management queries. |
| ENABLE_FILESYNC_RESPONSE | 0, 1 | NA | (see Description) | 1 | A value of 1 enables responses to the newer Filesync log transfer method on this source. Defaults to global option. TimeKeeper responds to Filesync queries if both source and global options are enabled and this source is enabled to respond to management queries. |
| ENABLE_MANAGEMENT_QUERY | 0, 1 | NA | (see Description) | 1 | A value of 1 enables this particular source to query PTP systems for their time sync quality data. Defaults to global option. Please see the ENABLE_MANAGEMENT_QUERY option in the global option section for more details. |
| ENABLE_MANAGEMENT_RESPONSE | 0, 1 | NA | (see Description) | 1 | A value of 1 allows this particular source to respond to incoming PTP management data requests. Defaults to global option. Please see the ENABLE_MANAGEMENT_RESPONSE in the global option section for more details. |
| ENABLE_PREFILESYNC _MANAGEMENT_RESPONSE |
0, 1 | NA | (see Description) | 1 | A value of 1 enables responses to PTP management queries from the management data transfer method that preceded Filesync. Only enable this if your client should respond to both Filesync and the older management query method. Defaults to global option. TimeKeeper responds in this way if both source and global options are enabled and this source is enabled to respond to Filesync management queries. |
| FILESYNC_END_TIME | 00:00:00 - 24:00:00 |
NA | 24:00:00 | 09:00:00 | A text field formatted as ‘HH:MM:SS’ (hours, minutes, seconds) offset from UTC midnight indicating when the Filesync of transferring client log files between servers and clients is required to end for this source. This overrides the global value and the default is equivalent to ‘24:00:00’, that is, the end of the day. |
| FILESYNC_START_TIME | 00:00:00 - 24:00:00 |
NA | 00:00:00 | 08:00:00 | A text field formatted as ‘HH:MM:SS’ (hours, minutes, seconds) offset from UTC midnight indicating when the Filesync method of transferring client log files between servers and clients is allowed to start for this source. This overrides the global value. Together with ‘FILESYNC_END_TIME’ it defines a range during which transfers may occur. |
| IFACE | text | NA | NA | ‘eth5.5’ | This source should watch the named interface for PTP data, where the interface name corresponds with a Linux network device name. |
| IPTOS | 0 - 255 | NA | 16 | 128 | The IP ToS value as an integer. For conversion to DSCP, use standard conversions. This has no effect on Windows. |
| PTP_P2P | 0, 1 | NA | 0 | 1 | If set to 1, the client uses P2P, the peer to peer delay measurement mechanism. Otherwise, the client uses E2E, the end to end delay measurement mechanism. |
| PTP_PROFILE | text | NA | NA | ‘automotive’ | The PTP profile to use in communicating with the PTP server. Only the automotive profile can be specified. |
| PTP_SYNC_RATE | 0.015625 - 128 | pps | 1 | 4 | The rate that the client requests the PTP server to send telecom-profile sync messages. Actual rate rounds to nearest power of 2 towards 1. For example, a value of 5 results in 4 sync messages per second and a value of 0.7 results in 1 sync message per second. |
| PTPCLIENTVERSION | 1, 2 | NA | NA | 2 | Most users will want version 2. |
| PTPDOMAIN | 0 - 255 | NA | 0 | 10 | The domain that TimeKeeper will watch for PTP data on. |
| PTPSERVER | text | NA | NA | 10.0.0.90 | The IP or DNS name of the unicast PTP server to be used. |
| PTP_LAYER2 | 0, 1 | NA | 0 | 1 | If set to 1, the client communicates via 802.3 (raw Ethernet frames/Layer 2 packets), otherwise will default to communicating via IPv4. PTP_LAYER2 is only supported on Linux. Cannot be used with the IPV6 source configuration parameter. |
| TTL | 0 - 255 | hops | 1 | 22 | How long a PTP packet should live when routed. |
| UNICAST | 0, 1 | NA | 0 | 1 | A value of 1 enables unicast delay requests back to the server. Ignored if PTPSERVER is specified. |
Local bus device options
| Option | Values | Units | Default | Example | Description |
|---|---|---|---|---|---|
| BAUD | 4800, 9600, 19200, 38400, 57600, 115200 |
bps | NA | (see Description) | Override default baud rate for this device. Default is 9600 for Spectratime, 115200 for Jackson Labs and u-blox, and 4800 otherwise. |
| DISABLE_GPS | 0, 1 | NA | 0 | 1 | Use other sources to steer the oscillator for holdover, disabling the GPS. |
| GNSS_BEIDOU | 0, 1 | NA | 0 | 1 | If set to 1, use of the BeiDou GNSS is enabled on the TimeKeeper GNSS device or PPSDEV device named. If BeiDou and GLONASS are enabled along with GPS and/or Galileo, BeiDou will be disabled because the GNSS device cannot support that combination. Only applicable if TKGPS on a second generation TimeKeeper grandmaster, TKJS or UBLOX is set to 1. |
| GNSS_GALILEO | 0, 1 | NA | 0 | 1 | If set to 1, use of the Galileo GNSS is enabled on the TimeKeeper GNSS device or PPSDEV device named. If no GNSS is enabled, Galileo will be enabled by default for TK GNSS GM. Only applicable if TKGPS on a second generation TimeKeeper grandmaster, TKJS or UBLOX is set to 1. |
| GNSS_GLONASS | 0, 1 | NA | 0 | 1 | If set to 1, use of the GLONASS GNSS is enabled on the TimeKeeper GNSS device or PPSDEV device named. Only applicable if TKGPS on a second generation TimeKeeper grandmaster, TKJS or UBLOX is set to 1. |
| GNSS_GPS | 0, 1 | NA | 0 | 1 | If set to 1, use of the GPS GNSS is enabled on the TimeKeeper GNSS device or PPSDEV device named. If no GNSS is enabled, GPS will be enabled by default. Only applicable if TKGPS on a second generation TimeKeeper grandmaster, TKJS or UBLOX is set to 1. |
| HOLDOVER_LIMIT | 0.0 - | seconds | 7200.0 | 60 | How long to remain in holdover before cross checking time against other sources. |
| PIN | 0 - | NA | 0 | 6 | Specify a ‘pin’ for PPS input/output. |
| PPSDEV | text | NA | NA | ‘/dev/ttyS0’ | The name of the device to be used. Refer to other sections of this document for details in what names can be used. |
| PPSOUT | 0, 1 | NA | 0 | 1 | For a PPS input/output device configure specified pin as ‘output’ rather than ‘input’. |
| PPSSOURCE | text | NA | NA | ‘tkgpio,eth4,0’ | An alternative name/location to get a PPS from. |
| TKGPS | 0, 1 | NA | 0 | 1 | If set to 1, like on a TimeKeeper grandmaster appliance, the source will be assumed to be a TimeKeeper GNSS/GPS device. |
| TKJS | 0, 1 | NA | 0 | 1 | If set to 1, the PPSDEV device named will be assumed to be a Jackson Labs GPS/GNSS device. GPS is the default. |
| TKPPS | 0, 1 | NA | 0 | 1 | Configures the source as a TimeKeeper PPS in/out card. |
| UBLOX | 0, 1 | NA | 0 | 1 | If set to 1, the PPSDEV device named will be assumed to be a u-blox GNSS device. |
General source options
There are some generally applicable configuration options that may apply to any source. Please refer to other sections of this document for specifics on their use:
| Option | Values | Units | Default | Example | Description |
|---|---|---|---|---|---|
| CABLEDELAY | (any decimal) | seconds | 0.0 | 0.000000271 | This can be used to correct timing biases induced by long GPS cable runs or other known causes of signal delay. This value is added to the incoming timing data, so with a long cable run that delays signal by 1 millisecond, use CABLEDELAY=0.001 to make TimeKeeper add 1ms to account for it. |
| ENABLE_HWTSTAMPS | 0, 1 | NA | 1 | 1 | TimeKeeper enables and uses hardware timestamping by default. Setting this value to 0 for a specific source will prevent TimeKeeper from using hardware timestamps, but only for that source. |
| IPV6 | 0, 1 | NA | 0 | 1 | If set to 1, TimeKeeper communicates via IPv6 for that source, otherwise will default to communicating via IPv4. IPv6 is only supported on Linux. |
| LABEL | text | NA | NA | ‘GrandMaster One NY’ | User defined string for easy reference. |
| LOWCPU | 0, 1 | NA | 0 | 1 | If set to 1 low CPU consumption is prioritized over accuracy and better noise rejection. The result is much lower CPU overhead and slight reduction in accuracy. |
| LOWQUALITY | 0, 1 | NA | 0 | 1 | A value of 1 means TimeKeeper will treat the source as low quality and apply additional filtering as well as using more data from the time source. When set this will also cause TimeKeeper to prioritize small and smooth adjustments over aggressively tracking the time from this source so it will react more slowly to erratic changes in the time source. Note that this will increase CPU consumption. See the slew section for more detail. |
| MAJORTIME | text | NA | NA | SOURCE3 | This source should get major (non-sub-second) timing data from the named source. Provide the full name of the source that will provide time of day information. |
| MONITORONLY | 0, 1 | NA | 0 | 1 | TimeKeeper will track the time source for informational purposes only, but will not allow the source to set the time on the local host if set to 1. |
| SYNCERRORTHRESHOLD | 0.0 - | seconds | 0.0 | 0.0001 | If the source’s sync quality exceeds this threshold, send an alarm. (e.g., SYNCERRORTHRESHOLD=0.000010 sends alarms if the sync quality exceeds +-10us). A threshold violation will only be reported after the error has been seen to be below the threshold first. A special value of 0 disables the alarm and is the default. |
Per PTP server options
When creating a PTP server, these options may apply:
| Option | Values | Units | Default | Example | Description |
|---|---|---|---|---|---|
| ENABLE_FILESYNC_QUERY | 0, 1 | NA | (see Description) | 1 | A value of 1 enables queries for the newer Filesync log transfer method for this server. Defaults to global option. TimeKeeper sends Filesync queries if both server and global options are enabled and this server is enabled to send management queries. |
| ENABLE_FILESYNC_RESPONSE | 0, 1 | NA | (see Description) | 1 | A value of 1 enables responses to the newer Filesync log transfer method responses. Defaults to global option. TimeKeeper responds to Filesync queries if both server and global options are enabled and this server is enabled to respond to management queries. |
| ENABLE_MANAGEMENT_QUERY | 0, 1 | NA | (see Description) | 1 | A value of 1 enables this particular server to query PTP systems for their time sync quality data. Defaults to global option. Please see the ENABLE_MANAGEMENT_QUERY option in the global option section for more details. |
| ENABLE_MANAGEMENT_RESPONSE | 0, 1 | NA | (see Description) | 1 | A value of 1 allows this particular server to respond to incoming PTP management data requests. Defaults to global option. Please see the ENABLE_MANAGEMENT_RESPONSE option in the global option section for more details. |
| ENABLE_PREFILESYNC _MANAGEMENT_RESPONSE |
0, 1 | NA | (see Description) | 1 | A value of 1 enables responses to PTP management queries from the management data transfer method that preceded Filesync. Only enable this if your client should respond to both Filesync and the older management query method. Defaults to global option. TimeKeeper responds in this way if both server and global options are enabled and this server is enabled to respond to Filesync management queries. |
| FILESYNC_END_TIME | 00:00:00 - 24:00:00 |
NA | 24:00:00 | 09:00:00 | A text field formatted as ‘HH:MM:SS’ (hours, minutes, seconds) offset from UTC midnight indicating when the Filesync of transferring client log files between servers and clients is required to end for this server. This overrides the global value and the default is equivalent to ‘24:00:00’, that is, the end of the day. |
| FILESYNC_START_TIME | 00:00:00 - 24:00:00 |
NA | 00:00:00 | 08:00:00 | A text field formatted as ‘HH:MM:SS’ (hours, minutes, seconds) offset from UTC midnight indicating when the Filesync method of transferring client log files between servers and clients is allowed to start for this server. This overrides the global value. Together with ‘FILESYNC_END_TIME’ it defines a range during which transfers may occur. |
| IFACE | text | NA | NA | ‘bond0’ | This server should use the named interface for PTP data, where the interface name corresponds with a Linux network device name. |
| IPTOS | 0 - 255 | NA | 16 | 184 | The IP ToS value as an integer. For conversion to DSCP, use standard conversions. This has no effect on Windows. |
| IPV6 | 0, 1 | NA | 0 | 1 | A value of 1 enables this server to distribute time via multicast IPv6 to clients, otherwise it will default to multicast IPv4. NOTE: By default PTP servers are enabled for both IPv4 and IPv6 unicast traffic. IPv6 is only supported on Linux. |
| LABEL | text | NA | NA | ‘Lan Segment 10.x Domain 0’ | User defined string for easy reference. |
| MINCLOCKACCURACY | 0.0 - | seconds | 0.0 | 0.010000000 | Floor for the accuracy advertised by the PTP server. This can be useful for clients that misbehave and switch grandmasters too quickly. |
| PTP_OVERRIDE_BC_PRIORITY | 0, 1 | NA | 0 | 1 | Allows a PTP server to over-ride the PTP priority 1 and 2 fields. Normally those values are taken from the upstream PTP source. When this option is set to 1 the priority fields are set from PTPPRIORITY1 and PTPPRIORITY2 rather than the upstream PTP source. |
| PTPPRIORITY1 and PTPPRIORITY2 |
0 - 255 | NA | 128 | 249 | These values are broadcast by the PTP server with announce messages. |
| PTPSERVERDOMAIN | 0 - 255 | NA | 0 | 6 | This indicates which domain the PTP server will broadcast on. |
| PTPSERVERSYNCRATE | 0.015625 - 128.0 | pps | 1.0 | 2.0 | The rate to multicast PTP sync and announce messages in packets per second. PTPSERVERSYNCRATE=1 causes TimeKeeper to multicast a sync every second (a value of 2 will send two sync messages every second). NOTE: Prior to TimeKeeper version 8.0.12, PTPSERVERSYNCRATE determined both the multicast and telecom sync and announce rates at the server, and the server ignored any client-requested rates. Starting with 8.0.12, PTPSERVERSYNCRATE still specifies the multicast sync and announce rates, but the server now obeys the client-requested rates. If you had been setting PTPSERVERSYNCRATE on the server to specify the telecom rates for all clients, you will now have to configure your clients so that they request the correct, desired rates. |
| PTPSERVERTTL | 0 - 255 | hops | 1 | 2 | How long a multicast PTP packet should live when routed. (A value of 0 effectively disables transmission of multicast PTP messages from this server.) |
| PTPSERVERVERSION | 1, 2 | NA | NA | 2 | Most customers will want version 2. |
| PTP_LAYER2 | 0, 1 | NA | 0 | 1 | If set to 1, the client communicates via 802.3 (raw Ethernet frames/Layer 2 packets), otherwise will default to communicating via IPv4. PTP_LAYER2 is only supported on Linux. Cannot be used with the IPV6 server configuration parameter. |
| PTP_PROFILE | text | NA | NA | ‘automotive’ | The PTP profile the server will use for communication. Only the automotive profile can be specified. |
| SYNCERRORTHRESHOLD | 0.0 - | seconds | 0.0 | 0.0001 | If management queries and SNMP traps or email alerts are enabled, any clients reporting a sync exceeding this threshold will cause an alarm to be triggered. (e.g., SYNCERRORTHRESHOLD=0.000010 sends alarms if any client sync quality exceeds +-10us). A threshold violation will only be reported after the error has been seen to be below the threshold first. A special value of 0 disables the alarm. |
| UNICAST | 0, 1 | NA | 0 | 1 | If set to 1, the server will provide unicast delay responses, whether the client provided a unicast or a multicast delay request. Otherwise, the server will respond with the same type of message as the request (multicast response for a multicast request, unicast response for a unicast request). |
Compliance report options
When creating a Compliance report, these options may apply:
| Option | Values | Units | Default | Example | Description |
|---|---|---|---|---|---|
| ALERTTHRESHOLD | 0.0 - | seconds | (see Description) | 0.00005 | Clients that exceed this value will be flagged as in an alert state and out of compliance. Not specifying this value disables the feature. |
| CLIENTSET | text | NA | NA | ‘*-ldn.domain.com’ | A string identifying which hosts should be included in this report, specified as one or a series of glob-like patterns separated by commas. Clients will be included in the report if their IP address or hostname match one of the patterns. |
| DAYS | text | NA | NA | 1,2,3,4,5 | Specifies the days on which the report is to include data specified as each of the numbers 0-6 inclusive where 0 is Sunday and 6 is Saturday. The default, empty, is to include all days and is equivalent to “0,1,2,3,4,5,6”. DAYS can also be specified as “Sun,Mon,Tue,Wed,Thu,Fri,Sat” for their English day short names. |
| ENDTIME | 00:00:00 - 48:00:00 |
NA | NA | 21:00:00 | Specifies offset from midnight (00:00:00 hours) UTC that the report will END in its coverage of the day. A 0 value indicates ending at the following midnight UTC. STARTTIME and ENDTIME can cover a period of time up to 24 hours. Please refer to the Compliance configuration documentation for details and examples. |
| ENDTOENDACCURACY | 0, 1 | NA | 0 | 1 | If set, Compliance will include the reported upstream accuracy in any offset threshold calculations. |
| EXCLUDEDCLIENTSET | text | NA | NA | ‘www.*’ | Which hosts should not be included in this report, specified as one or a series of glob-like patterns separated by commas. Clients will be excluded from the report if their IP address or hostname match one of the patterns. Exclusion takes precedence over inclusion so if a host is included by “CLIENTSET” but excluded by “EXCLUDEDCLIENTSET” it will not be included in the report. |
| MINALERTCOUNT | 0 - | alerts | 0 | 10 | Specifies the minimum number of alerts that a client must have across all sources within the configured day (based on UTC midnight or STARTTIME/ENDTIME) in order for alerts to be included in the audit. A value of 0 means all violations are reported. A client with fewer alerts than this value will not have its alerts recorded/reported on; otherwise each alert will be reported in full. Please refer to the Compliance configuration documentation for details. |
| MINALERTLENGTH | 0 - | seconds | 0 | 1 | A client exceeding the alert threshold will only be flagged as being out of compliance if it stays above the threshold for MINALERTLENGTH seconds. A value of 0 means any single sample above the alert threshold will constitute a violation. |
| MINGAPLENGTH | 15 - 86400 | seconds | 180 | 15 | A client missing data for more than MINGAPLENGTH seconds will be flagged as having a gap in its data. |
| MINWARNINGLENGTH | 0 - | seconds | 0 | 1 | A client exceeding the warning threshold will only be flagged as being in a warning state if it stays above the threshold for MINWARNINGLENGTH seconds. Not specifying or setting a value of 0 means any single sample above the warning threshold will constitute a violation. |
| ONLYREPORTPRIMARY | 0, 1 | NA | 0 | 1 | When set, only process issues on a client/source if that source is or may be primary at the time of the issue. Non-primary sources will not have threshold violations recorded. If the reporting client data doesn’t indicate what source was primary, it’s assumed that may be and will be processed. (TimeKeeper versions 7.2.14 and above include this detail for processing.) |
| STARTTIME | 00:00:00 - 24:00:00 |
NA | NA | 13:00:00 | Specifies the offset from midnight (00:00:00 hours) UTC that the report will START coverage in its output. The default value indicates starting at midnight UTC. |
| TITLE | text | NA | NA | ‘London hosts’ | A string naming a particular report. |
| WARNINGTHRESHOLD | 0.0 - | seconds | (see Description) | 0.000025 | Clients that exceed this value will be flagged as in a warning state. This feature detects clients that may get near the alert threshold before the alert threshold is reached. Not specifying this value disables the feature. |