DTLinux configuration is simple and straightforward. All configuration (with the exception of configuring the
dtlinux.keys file for symmetric authentication) is done by editing the dtlinux.conf file.
See a sample here: dtlinux.conf.sample.txt.
Both the dtlinux.conf and dtlinux.keys files are heavily commented and are the primary documentation for DTLinux. You should always keep a copy of the original
distribution files available for reference in case the comments in your running copies are inadvertently removed during editing.
This online documentation page merely highlights a few of the topics for additional discussion.
NTP and DT2 Time Sources
This section covers how to configure DTLinux to obtain time from NTP and/or DT2 time sources.
You can manually specify the sources in the dtlinux.conf file and DTLinux can also obtain a list
of sources from DHCP options.
Selecting the correct time sources are critical for accurate timing.
The Internet time sources specified in the default .conf file are intended as examples only. Choose servers
that are optimal for your environment. Stable time sources on a local subnet are best.
Loop Variables
You can set the time check intervals using the parameters in the section. You also control whether to keep
ntp-style loopstats and peerstats files, and a CSV file of PTP stats.
A loop:checkInterval of 60 is recommended if you are using PTP to allow PTP time to collect enough valid samples
to analyze statistically for best performance. Otherwise, if using NTP or DT2, set the value low enough to
acheive the accuracy you require. Setting the value too low just increases overhead and network traffic.
Also, set a reasonable loop:errorInterval. The value should normally be 30 seconds or less. This affects the period
between DTLinux detecting a loss of sync with time sources and when it retries a connection. A relatively short error interval
is desireable to restore sync quickly when sources become available again.
The loop:checkAll setting determines whether all the configured NTP and DT2 time sources are included and analyzed in each time check
or if the list is used for fallback, where the first server is used until it fails, at which point the next machine in the list is tried.
You may set the log level to Trace (log:logLevel = Trace) if you want to see the details on which machines are used in
each time synchronization.
loop:loopStatsEnabled controls whether to keep NTP-style loopstats files. loop:peerStatsEnabled controls whether to keep NTP-style peerstats files. loop:ptpStatsEnabled controls whether to keep a CSV file of PTP stats.
The peerstats and loopstats, and the CSV ptpstats file, are kept in
the same folder as the main DTLinux log, and roll according to the log:logRetention
value. If log:logRetention is zero, a new file is started each day at
local midnight, and previous contents are erased.
The peerstats filename is
dtlinux-peerstats. The loopstats filename
is dtlinux-loopstats. The ptpstats filename is dtlinux-ptpstats.
See the ntpd Compatibility page for details on formats.
PTP Settings
Use this section to enable/disable PTP and set its basic parameters.
See the PTP Profiles section of the main PTP page for
information on which PTP Profiles DTLinux supports.
Be sure to use DTLinux's ability to view available PTP Masters when troubleshooting synchronization issues:
From the Terminal:
dtcheck -ptpmasters
From Domain Time Manager:
Choose Graphs & Statistics -> Open PTP Statistics & Masters from the Manager menu to disply the PTP Statistics page.
PTP 1588-2019 (v2.1) Security
DTLinux supports PTP v2.1 (IEEE 1588-2019) which features enhanced security features. You enable these features by
setting the options in this section.
There are six true/false settings related to PTP v2.1 security. The default for all is false.
= false ; enable v2.1 security?
= false ; prefer signed announces?
= false ; require signed announces?
= false ; require signed syncs?
= false ; require signed delay responses?
= false ; sign outgoing delay requests?
If
ptpSecurity:enabled is false, the remaining settings are ignored. No PTP v2.1 security TLVs are processed.
If
ptpSecurity:enabled is true, then the following options obtain:
If
ptpSecurity:preferSignedAnnounces is true,
then Best-Master-Clock (BMC) algorithm is altered to give priority to masters that sign their Announces.
This configuration allows a mix of v2.0 and v2.1, so that the normal BMC applies if no master signs Announces.
If ptpSecurity:requireSignedAnnounces is true,
then only masters that provide signed announces will be considered.
If
ptpSecurity:requireSignedSyncs is true,
then if the selected master is v2.1 and sending signed Announces, signed Syncs/Follow-Ups are also required.
If your master signs Announces but not Syncs, DTLinux will not be able to follow it.
If
ptpSecurity:requireSignedDelayResp is true,
then if the selected master is v2.1 and sending signed Announces, signed delay
responses are also required. If your master signs Announces but not
delay responses, then DTLinux will not be able to calculate the
meanPathDelay, and your synchronization quality will suffer.
If
ptpSecurity:signOutgoingDelay is true,
and the selected master is v2.1 and sending signed Announces, DTLinux will sign delay
requests according to the key numbers you have selected. Some
v2.1 masters send unsigned delay responses if the delay request
is unsigned. Some always sign delay responses. Others will ignore
unsigned delay requests. Check with your appliance manufacturer's
documentation to decide whether or not to sign delay requests and
require signed delay responses.
You should normally leave
ptpSecurity:requireSignedDelayResp and
ptpSecurity:signOutgoingDelay set to false, unless required by
your grandmaster appliance. There is no real security benefit to
signing delay requests or requiring signed delay responses.
The /etc/opt/domtime/dtlinux.keys file contains the symmetric keys
and also the PTP v2.1 key numbers to use for signing packets.
MD5 and SHA1 keys are used with NTP and DT2. PTP v2.1 keys must
be either SHA256 or SHA512. In order to verify signed incoming
packets, you must have SHA256 or SHA512 keys corresponding to
whatever the master sends for Announces, Syncs, Follow-Ups,
and delay responses.
In order to sign a delay request, you must have an SHA256 or
SHA512 key known to the master, and you must select the key
number to use. For example, if SHA256 keys 24 and 26 exist
in your keyring, you set the values in the dtlinux.keys file
as follows:
You should not use SHA512 keys. DTLinux supports them in the
keyring and will use them if the master sends an SHA512 key,
but most masters only support SHA256. In particular, the only
defined algorithm for PTP v2.1 is HMAC-SHA256-128. This will
change when NTS (RFC 8915) is adapted for use with PTP and
appliance manufacturers accommodate it. In the meantime, use
SHA256.
The /etc/opt/domtime/dtlinux.keys file also contains a Security Parameter Pointer (SPP) value, range 0-255. For example:
ptpSPP 0 # Security Parameter Pointer
If the ptpSPP value is zero, then DTLinux will accept any SPP value
sent by the master. When sending delay requests, DTLinux will use
the SPP of the master.
If the ptpSPP value is non-zero, it must match the SPP value sent
by the master. If the values don't match, then neither incoming
packets nor outgoing delay requests will verify correctly.
Domain Time II Real-Time Alerts
If you are using Domain Time II Audit Server, we suggest you enable Real-Time Alerts in this section, even if you haven't
yet configured any Real-Time Alerts in Audit Server. This will cause the DTLinux machine to display in the Real-Time Alerts
page of Manager, giving you up-to-date information on synchronzation status and accuracy.
Domain Time II Security
Settings in this section control remote access to DTLinux from Domain Time II Manager.
The dt2Security:allow entries specify IP addresses or CIDR masks that control which IPs are allowed to connect to
DTLinux. The default entries include the RFC 1918 private network blocks. You should remove any entries that don't correspond
to the networks where you have Domain Time II Manager or Audit Server installed. To prevent all remote access, change the
first dt2Security:allow entry to 127.0.0.1 and comment out (or delete) the remainder.
Assuming you have granted IP access to Manager, the dt2Security:managerReadOnly entry controls whether or not Manager
is allowed to make any changes. If you set this value to true, then Manager will still be able to view settings, and Audit Server
will still be able to audit the machine, but Manager will be prevented from making any changes to the configuration. If you set
this value to true, then you must manually edit the dtlinux.conf file on the remote machine to change it back to false. By
design, there is no remote method available for changing this value from true to false.
The dt2Security:managerRestart entry controls whether or not Manager is allowed to restart the DTLinux service remotely.
It has no effect if dt2Security:managerReadOnly is true.
The dt2Security:managerUpgrade entry controls whether or not Manager is allowed to upgrade the DTLinux service and associated
file remotely. It has no effect if dt2Security:managerReadOnly is true.
Please read /opt/domtime/UpdatingDTLinux.html for information on using the dtcheck command-line utility to limit key functions
to only specific Managers.
Cloning
If you use cloned OS images to install machines, please read this article
from our knowledgebase about configuring Domain Time properly on your clone image.
License: Commercial Proprietary (registration required)
This section describes the evaluation period and how to register the software. The section will
be removed when the software is registered.
The dtlinux.keys file
This file contains the authentication keys used for the DT2, NTP, and/or PTP v2.1 protocols.
It's also referred to as your keyring. It's located in the
/etc/opt/domtime/ folder.
The keyring may contain a combination of trusted and untrusted keys. A trusted key means the key
is available to be selected by the component, but trusted keys for DT2 and NTP are not active
until their key number is specified when configuring a DT2 or NTP time source in the time sources
list of the dtlinux.conf file (i.e.
timesource = 192.168.1.3 protocol NTP key 5).
Trusted keys for PTP v2.1 aren't active unless PTP Security has been enabled. Untrusted keys are ignored.
Here are values from a sample keyring, with MD5 keys available for use by DT2 or NTP, and SHA256 keys available for PTP v2.1:
The Trustedkey line in the file specifies which keys in the keyring are trusted, i.e.:
Trustedkey 1 2 3 4 9909
The file also contains additional settings required for PTP v2.1 authentication.
ptpSPP sets the Security Parameter Pointer (SPP). PTP v2.1 requires that Masters and Slaves use the same SPP
value to be able to authenticate. The SPP stored in the keyring may either be zero (which acts like a wildcard) or must match what
the grandmaster sends. If there is a potential for your Slaves to discover more than one Master (such as with a fallback server),
we recommend you use the wildcard setting (0) to avoid synchronization failure if each server has a different SPP.
These entries specify the key number of the secret that Masters use for signing outgoing packet types. They are included here
for compatibility when importing the .keys file into Domain Time Server. These parameters are ignored by Domain Time Client
and DTLinux :
ptpAnnounce
[key #]
ptpSync
[key #]
ptpDelayResp
[key #]
ptpPDelayResp
[key #]
These entries specify the key number of the secret used for signing packet types sent by the Slave:
ptpDelayReq
[key #]
ptpPDelayReq
[key #]
Sharing the keyring file.
For symmetric authentication to work, the keyring must be shared among all devices that wish to use it. The dtlinux.keys file
uses a format compatible with most time daemons (i.e. ntpd's ntp.keys, chrony's chrony.keys, etc.). You can usually simply
copy the
/etc/opt/domtime/dtlinux.keys file to your target system (rename it if necessary).
You can also copy the
/etc/opt/domtime/dtlinux.keys file from one DTLinux machine to another.
You may also share the dtlinux.keys file with Domain Time Servers and Clients on Windows (and vice versa). Use the
Import/Export link on the Symmetric Keys
property page of the Server or Client's applet to import or export the .keys file.
If you are using Domain Time II Manager, you can use the Reset Keyring
function to push out the keyring to all of your Windows Servers and Clients and DTLinux machines at once. The
Reset Keyring function uses the
keyring of the Domain Time Server on which Manager is installed. So, to easily share a DTLinux machine's keyring among all of your other
Domain Time systems, you'd import the keyring file into
Manager's Domain Time Server and then select the machines you want to update and use the
Reset Keyring command from the right-click context menu.
DTLinux Configuration
Proceed to the Managing DTLinux Remotely page
Back to the Installation Instructions page