------------------------------------------------------------------------------ D O M A I N T I M E II C L I E N T Domain Time II for Linux (dtlinux) ------------------------------------------------------------------------------ Microsemi Corporation 3870 N. First Street San Jose, CA 95134 Voice Phone: 1-408-428-7907 1-800-367-7966 Documentation: http://dtdocs.ntp-systems.com/ Support Portal: https://www.microsemi.com/products/timing-synchronization-systems/timing-synchronization-systems-support ------------------------------------------------------------------------------ EVALUATION PERIOD ------------------------------------------------------------------------------ This program is NOT freeware. It is an evaluation copy distributed on a try- before-you-buy basis. Your evaluation period is thirty (30) days from when you first install dtlinux. IMPORTANT: dtlinux will stop steering the system clock after the evaluation period has expired. In order to continue using dtlinux after the evaluation period, you must obtain and apply a license key. ------------------------------------------------------------------------------ R E Q U I R E M E N T S ------------------------------------------------------------------------------ 1. x86_64 Linux distro running in 64-bit mode Tested successfully on CentOS7, CentOS8, RHEL 8.3, Ubuntu 20, OpenSUSE Tumbleweed, Fedora 33, Mint 20, Ubuntu 18, and OracleLinux 8.3 2. Kernel version 2.6.30 (minimum), version 3.0 or later (preferred) 3. systemd init system (not the older inet.d "SysV" service controller) ------------------------------------------------------------------------------ S E T U P I N S T R U C T I O N S ------------------------------------------------------------------------------ 1. Download the latest version of dtlinux from http://dtdocs.ntp-systems.com/tryout/domtime/dtlinux/ This is a browsable folder where you may obtain the SHA256 hashes, read the changelog or other files, and also download the packages. There are three flavors of packaging available: * TGZ offers the most flexibility. It is a zipped TAR, containing all of the necessary files, along with scripts to install, update, or remove the product. It will work on older systems where DEB or RPM packages don't install or upgrade correctly. * DEB is a Debian package for Debian and derived distros, like Ubuntu. Install or upgrade using: echo N | sudo apt-get install Remove using: sudo apt-get -y remove --purge dtlinux * RPM is useful for RedHat, CentOS, and other RPM-based systems. Install or upgrade using: sudo rpm -U Remove using: sudo rpm -e dtlinux NOTE: Some distros offer a graphical package installer. We recommend using the command line instead, because not all graphical installers are able to upgrade in place, instead doing a remove followed by an install. This will lose your settings. The command line options for RPM and DEB (rpm -U or apt-get install) will upgrade in place, preserving settings. The install, remove, and update scripts will detect if you have used apt, rpm, or a TGZ, and act appropriately. The advantage of DEB and RPM packages is that your system database will know about dtlinux, and allow you to manipulate it using your standard tools. The advantages of using a TGZ are that it's distro-independent, and offers more flexibility and control. 2. For first-time TGZ installs, unpack the files into a temp folder and run the install.sh script. For example: mkdir dtlinux # make a temp folder tar -xf -C dtlinux # extract to temp folder sudo ./dtlinux/install.sh # install or upgrade 3. To upgrade, run sudo dtlinux-update, or execute this script directly: sudo /opt/domtime/update.sh This script will download, unpack, and upgrade for you. The update.sh script will determine if you previously installed using an RPM, DEB, or TGZ, download the corresponding type of file, and execute the proper commands. NOTE: If your machine does not have Internet access, transport the newer RPM, DEB, or TGZ manually, and run step 2 for TGZ, or follow the instructions in step 1 for RPM or DEB. 4. If you have obtained a license key, you may apply it remotely using Domain Time II Manager, or you may apply it from your Linux command line. Open a terminal window, and run the following: sudo dtlinux -registration=xxxxxxxx-yyyyy Substitute your registration code for xxxxxxxx-yyyyy. HIGHLY-RECOMMENDED: After applying your license key, use the Linux command line to run sudo dtcheck -backup. This preserves your settings and license in case you mistakenly remove instead of upgrading. You may restore backed-up settings by running sudo dtcheck -restore. Use dtcheck -help for a more detailed explanation. To remove an existing installation (regardless of how you installed it): Run this script: sudo /opt/domtime/remove.sh If you installed using RPM or DEB packages, you may use the operating system tools. The remove script works no matter how you installed, and does a better job of cleaning up post-remove artifacts. To see if a newer version of dtlinux is available: run sudo dtcheck -update If a newer version is available, this command will provide the download link you should use. ------------------------------------------------------------------------------ C O N F I G U R A T I O N ------------------------------------------------------------------------------ 1. After first installation, you will need to edit the main configuration file: /etc/opt/domtime/dtlinux.conf (requires sudo). If you want to use symmetric key authentication for NTP, DT2, or PTP, you'll also need to edit /etc/opt/domtime/dtlinux.keys (requires sudo). *** Please use man dtlinux to read the dtlinux(8) manual page. 2. At a minimum, you should adjust the dt2Security section, substitute your own NTP or DT2 time sources for the defaults provided, and enable PTP (if you have a PTP appliance). 3. DTLinux can be fully managed using the Windows Domain Time II Manager product. Manager allows you to edit the dtlinux.conf file, push out an updated keyring, discover which network adapters support which kind of timestamping, and generate problem reports to submit to support. You can also view the log and statistics in real time. 4. When you first enable PTP, it can take 5-10 minutes for dtlinux to achieve stable sync. Thereafter, including reboots, dtlinux trains in quite quickly. 5. Virtual machines: On Hyper-V, enable the time sync integration service. On VMware or other hypervisors, disable all host-to-guest time synchronization options. 6. On a stand-alone machine, or a VM that supports passing hardware timestamping from the host to the guest, dtlinux will discover the NIC's timestamping capabilities, and use the best available type of timestamping. For NICs with built-in PTP engines, dtlinux does not attempt to control or guide the built-in PTP engine. It only uses the hardware timestamping features provided by the NIC to steer the system clock. If hardware or software timestamping performed by the NIC or the Linux TCP/IP stack is unreliable or produces false timestamps, you may disable timestamping by changing network:useTimestamping to false in dtlinux.conf. 7. Run /opt/domtime/help.sh, or open /opt/domtime/help.html, to access online help. ------------------------------------------------------------------------------ L O G F I L E O P T I O N S ------------------------------------------------------------------------------ All logging options are controlled by the dtlinux.conf file settings. Drift files (binary) are kept in the same folder as text logs, unless you specify a different log:driftPath. You may extract the data from binary drift files using dtcheck -csv or dtcheck -txt . The two possible binary drift files are drift.dt and driftptp.dt. These files automatically scroll off older data when the file size exceeds 64k data points. You may set the binary drift file for PTP to keep the meanPathDelay instead of the phase adjustment by changing the ptp:driftRecordsMPD value from false to true. If enabled, then dtcheck -csv output will have an extra column, labeled "Delay." The main log name is dtlinux.log. Older names will be dtlinux.yyyymmdd.log. NTP-style peerstats and loopstats, and the CSV ptpstats file, are kept in the same folder as the main 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 text log file (and echoing to syslogd) is controlled by log:logLevel: loglevel = 0 = NONE - off, no text log loglevel = 1 = ERROR - errors only loglevel = 2 = WARN - warnings and errors loglevel = 3 = INFO - info, warnings, and errors loglevel = 4 = TRACE - trace, info, warnings, and errors loglevel = 5 = DEBUG - debug, trace, info, warnings, and errors logLevel = 6 = SPEW - all of the above, plus extra debugging You may use either the numeric value or the name for log:logLevel. To enable echoing the text log output to syslogd, set log:echoToSyslog to true. Peerstats, loopstats, and ptpstats are optional, controlled by loop:peerStatsEnabled, loop:loopStatsEnabled, and loop:ptpStatsEnabled, respectively. NTP-style peerstats name: dtlinux-peerstats NTP-style loopstats name: dtlinux-loopstats CSV ptpstats name: dtlinux-ptpstats NTP-style peerstats and loopstats are text files, in the same format as produced by nptd. However, some fields will always be zero, because dtlinux is not based on ntpd, and doesn't provide the exact same kinds of counters. CSV-style ptpstats are text files. One line is generated for each PTP data point, with fields being separated by commas. The fields, from left to right are: Timestamp in ISO 8601 UTC format (string yyyy-mm-ddThh:mm:ssZ) PTP master's IP address (string) PTP master's portIdentity (string) PTP master's stepsRemoved from a primary reference (integer) PTP engine's servo status (s0 syntonizing, s1 step, s2 locked) Leap status (0 = no leap, 59 = backward leap, 61 = forward leap) PTP engine's current offsetFromMaster (signed nanoseconds) PTP engine's current meanPathDelay (unsigned nanoseconds) PTP engine's current phase adjusment (signed double) The CSV-style ptpstats file is updated at each timecheck interval, not as each data point arrives. The timecheck interval is controlled by the loop:checkInterval, and measured in seconds. You should be careful when enabling CSV-style ptpstats, because each line is ~90 characters long, and there can be up to 86,400 lines per day. When parsing the dtlinux-ptpstats file, take care to remember that the timestamps are in UTC, even though the file will roll or restart at local midnight.