------------------------------------------------------------------------------
                  D O M A I N   T I M E   II   C L I E N T 
                     Domain Time II for Linux (dtlinux)
------------------------------------------------------------------------------

Greyware Automation Products
308 Oriole Ct
Murphy, TX  75094

       Voice:  1-972-867-2794
Tech Support:  techsupport@greyware.com
       Sales:  sales@greyware.com
General Info:  info@greyware.com

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

Documentation:      https://www.greyware.com/
Windows Changelog:  https://www.greyware.com/changelog
DTLinux Changelog:  https://www.greyware.com/tryout/domtime/dtlinux/CHANGELOG.txt
Online Store:       https://www.greyware.com/store
Price Calculator:   https://www.greyware.com/prices

------------------------------------------------------------------------------
                            R E Q U I R E M E N T S
------------------------------------------------------------------------------

   1. x86_64 Linux distro running in 64-bit mode

   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)

   4. glibc v2.17 or newer

   5. A user with sudo privileges or su root privileges. Note that many
      modern distros will fail to install a systemd service using sudo. In
      those cases, su root, or actually logging on as root, may be required.

      *** In the instructions below, if sudo fails, substitute a method like
      su root to grant full root access instead of using sudo during
      installation or removal of DTLinux. ***

------------------------------------------------------------------------------
                      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
         https://www.greyware.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 <filename>

         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 <filename>

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

       a) Edit the dt2Security section of dtlinux.conf to limit IP ranges
          and Manager permissions.

       b) Use sudo dtcheck -setPassword to set a secure password for remote
          operations. Passwords are never sent over the wire, only an SHA256
          hash of the password plus salt and a nonce. Once set, Manager will
          need to provide the hash for most operations.

       c) Use sudo dtcheck -authorize NameOrIp to authorize Manager(s) you
          want to control dtlinux. If no Managers are explicitly authorized,
          then any Manager not restricted by (a) or (b) can manage dtlinux.
          If at least one is authorized, only those on the authorized list
          can perform most actions. Use dtcheck -help for more information.

   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 <filename> or dtcheck -txt <filename>.
  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.
