Top of Page

Installation Instructions  DTLinux Configuration
Domain Time DTLinux
Version 5.2

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.

The dtlinux.conf file

    The file is divided into functional sections:

    • 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.

        See the Planning for effective time distribution for help making the right choice.

    • 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.

    • 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.

          ptpSecurity:enabled
          ptpSecurity:preferSignedAnnounces
          ptpSecurity:requireSignedAnnounces
          ptpSecurity:requireSignedSyncs
          ptpSecurity:requireSignedDelayResp
          ptpSecurity:signOutgoingDelay
           = 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:

            ptpDelayReq   24  # End-to-End delay request key
            ptpPDelayReq  26  # Peer-to-Peer delay request key

          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:

    Key #TypeSecret
    1MD5DomainTimeII
    2MD5TTnts200
    3SHA256bf14d67e2ddc8e6683ef574961ff698f61cdd11e9d9c167272e61df0844f4a71
    4SHA25648d38f75e6d91d2ae5c0f72b788187440e5f5000d4618dbe7b0515073b338211
    5MD5greyware

    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.

 

Next Proceed to the Managing DTLinux Remotely page
Back Back to the Installation Instructions page

Domain Time II Software distributed by Microsemi, Inc.
Documentation copyright © 1995-2024 Greyware Automation Products, Inc.
All Rights Reserved
All Trademarks mentioned are the properties of their respective owners.