# Configuration file for dtlinux # Domain Time II for Linux # Copyright (c) 1995-2024 Greyware Automation Products, Inc. # Version 5.2.b.20240101 # License: Commercial Proprietary [ ----- File Locations ---------------------------------------------------- ] /etc/opt/domtime/dtlinux.conf main configuration file /etc/opt/domtime/dtlinux.keys symmetric keys /var/log/domtime/ default folder for log files [ ----- File Format ------------------------------------------------------- ] Blanks lines or lines beginning with space, tab, hashtag, semicolon, glitch/apostrophe, left-bracket, or right-bracket are treated as comments and ignored. Curly brackets (braces) must not appear in this file. Entries are of type keyword=value. Comments may be placed after the value. For example: network:sourcePortUDP = 3333 ; I want to use this port Lines in this file may be either LF- or CRLF-terminated. The encoding should be UTF-8 without a BOM. Non-English may appear in any comment, but keyword=value pairs must be ASCII text. Use systemctl reload dtlinux (or send SIGHUP) to signal the service that you have edited this file and want the changes recognized. Reload is not required if you edit this file remotely using Domain Time II Manager. [ ----- Other Time Software ---------------------------------------------- ] dtlinux is a complete NTP, PTP, and DT2 client. It will discipline the clock, respond to Domain Time queries, and optionally serve the time via NTP. It is vital that you don't have more than one program trying to own the various time ports, or trying to discipline the clock. Stop and disable ntpd, ptpd, ptp2d, linux4l, chronyd, linuxptp, etc., before installing this program. [ ----- NTP and DT2 Time Sources ------------------------------------------ ] Whether you are using PTP or not, you should configure at least one regular time source here. You may list any number of time sources. Supported protocols are NTP, DT2-UDP, and DT2-TCP. The server may be specified as a NetBIOS or DNS name, or as an IP literal. If the server name is not an IP literal (either IPv4 or IPv6) you may force the name resolution to use either IPv4 or IPv6, as shown in the examples below. timesource = 192.168.1.3 -- IPv4 literal, will use IPv4 timesource = tick.greyware.com -- DNS name, resolver will pick timesource = IPv4 tick.greyware.com -- DNS name, forced to use IPv4 timesource = IPv6 tick.greyware.com -- DNS name, forced to use IPv6 The only other parameter required is the protocol name (may be NTP, DT2-UDP, or DT2-TCP). Note that just "DT2" is the same as DT2-UDP. timesource = 192.168.1.3 protocol NTP timesource = 192.168.1.6 protocol DT2 If you have a DHCP server on your network configured with option 004 or option 042, you may use the keyword "dhcp" instead of an IP address or name. Option 004 is used for DT2 sources; option 042 is for NTP. For example: timesource = dhcp protocol NTP timesource = dhcp protocol DT2 Optional parameters are the number of samples, the delay in milliseconds between each sample (if more than one), the symmetric key number (if using MD5 or SHA1) and a comment (enclosed in quotation marks). You may also set a timesource to disabled (rather than commenting it out or deleting it), by including the keyword "disabled" as the first parameter. Several full ex- amples using various options are shown below. timesource = 2600:2f28:379:7622:7c4b:e279:e222:e0e4 protocol NTP timesource = 192.168.1.3 protocol NTP samples 3 delay 512 key 7 timesource = 192.168.1.6 protocol NTP samples 3 delay 512 timesource = IPv4 kenny protocol DT2-TCP samples 3 delay 512 timesource = 34.210.111.246 protocol DT2-UDP comment "tock.greyware.com" timesource = IPv4 tick.greyware.com protocol DT2 key 19909 timesource = 192.168.1.10 protocol DT2 comment "test server" timesource = dhcp protocol NTP samples 3 delay 128 timesource = disabled 192.168.1.12 protocol NTP comment "do not use" The delay parameter (only used if samples is greater than one) has a minimum of 16 milliseconds and a max of 1024 milliseconds. The default is 256 milli- seconds (~ 1/4 second). If at all possible, you should use local NTP appliances instead of Internet sources. You cannot obtain better sync than a handful of milliseconds unless you have an appliance or server on the local LAN. ##! Do not remove or alter this line (timesources) !## timesource = pool.ntp.org protocol NTP comment "Internet NTP pool source" timesource = tick.greyware.com protocol DT2-UDP comment "Internet DT2 server" timesource = tock.greyware.com protocol DT2-TCP comment "Internet DT2 server" [ ----- Loop Variables ---------------------------------------------------- ] The timecheck loop is how often timesources are checked and statistics updated. If you are using PTP, the timecheck loop only controls how often statistics are updated. You should set it to something reasonable for your environment. The checkInterval value controls the length of timecheck loop. The checkInterval is specified in seconds (min 5, max 28800). The errorInterval is also in seconds (min 15, max 28800). The checkAll value controls whether all listed time sources are consulted at each timecheck (true) or if checking stops after the first time source in the list that provides a valid time sample (false). loop:checkInterval = 60 ; check interval, in seconds loop:errorInterval = 30 ; error retry interval, in seconds loop:checkAll = true ; analyze all, or stop after first success? loop:loopStatsEnabled = false ; keep NTP-style loopstats files? loop:peerStatsEnabled = false ; keep NTP-style peerstats files? loop:ptpStatsEnabled = false ; keep CSV of PTP stats? [ ----- Logs and Folders -------------------------------------------------- ] 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 peerstats filename is dtlinux-peerstats. The loopstats filename is dtlinux-loopstats. The ptpstats filename is dtlinux-ptpstats. NTP-style peerstats and loopstats are optional, controlled by loop:loopStatsEnabled and loop:peerStatsEnabled. CSV-style ptpstats are optional, controlled by loop:ptpStatsEnabled. 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 If you change the folder defaults, dtlinux will attempt to create the new folders and move the files. If you change the folders while dtlinux isn't running, it won't move old files or try to remove the old folder. 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 logRetention = 0 - just use one log, restarted at local midnight logRetention = n - keep up to n old logs (max 365) log:logLevel = Info ; use the number or the name log:logRetention = 3 ; range 0-365 allowed log:echoToSyslog = false ; send to syslogd? log:logPath = /var/log/domtime ; folder for text logs log:driftPath = /var/log/domtime ; folder for binary drift files [ ----- Network Settings -------------------------------------------------- ] Change these settings only if the defaults don't work for you. If no adapterName is provided, dtlinux attempts to bind to all IPs on all adapters. If you want to limit which adapter is used, add the adapter's name. For many distros, multicast reception only works on the "primary" (i.e. first) adapter, unless you configure your machine's network to deliver multicasts to all adapters. Consult your distro's documentation on this issue. network:multicastLoopback and network:multicastTTL are only used with PTP. If network:multicastLoopback is true, then outgoing PTP multicasts will echo back up the stack for other programs to read. network:multicastTTL controls how many router hops (either IPv4 or IPv6) an outgoing multicast packet can traverse before expiring. A value of 1 means that packets cannot escape the local subnet. A value of 31 is the max allowed. network:useTimestamping allows you to disable the automatic use of soft- ware or hardware timestamping. By default, dtlinux will figure out the best available type of timestamping and use that. You can check an adapter's timestamping capabilities by using ethtool -T adaptername. network:igmpRefresh is useful when your router cannot verify your multi- cast group memberships and therefore drops you. Enable this option by setting it to a reasonable number of minutes (5-10 is normal). The two dscp values control network priorities for incoming multicasts on ports 319 and 320. The highest priority is 0x80. Use 0x00 to set the priority to the system default. network:enableIPv6 = false ; use true to use listen on both IPv4 and IPv6 network:adapterName = ; specify a Ethernet adapter name if desired network:multicastTTL = 8 ; allowed range is 1-31 network:multicastLoopback = false ; allow multicast loopback? network:sourcePortUDP = 0 ; see notes below in Firewall Advice network:useTimestamping = true ; Change only if problems occur network:ntpServerEnabled = false ; serve the time via NTP? network:ntpqEnabled = false ; respond to ntpq requests? network:port319dscp = 0x80 ; dscp for incoming on port 319 network:port320dscp = 0x60 ; dscp for incoming on port 320 network:igmpRefresh = 0 ; minutes - use 0 to disable [ ----- PTP Settings ------------------------------------------------------ ] Options for ptp:profile are: E2E End-to-End default profile P2P Peer-to-Peer default profile Auto determines E2E or P2P automatically Enterprise End-to-End Enterprise profile Telecom Telecom 2008 (negotiated unicast) E2E profile Disabled Delay requests disabled (for syntonization only) Options for ptp:delayTransport are: Multicast delay requests sent by multicast Hybrid delay requests sent by unicast Auto determines if master supports unicast If you want to limit the PTP masters, you may specify any number of multicast master IP addresses. If no multicast masters are specified, then PTP's normal Best-Master-Clock algorithm will select the best clock on your network. If you specify one or more multicast masters, then Announces from PTP masters other than the one(s) you specify will be silently discarded. A multicast master entry may be a specific IP or a CIDR mask. If you specify Telecom as the profile, then you must supply one or more Telecom masters. The format is telecomMaster = a.b.c.d,n where a.b.c.d is an IP address, and n is the domain number. When using the Telecom profile, ptp:multicastMaster entries, the ptp:domainNumber, and the ptp:delayTransport values are all ignored. example: telecomMaster=192.168.1.3,0 ; master 192.168.1.3, domain 0 example: telecomMaster=192.168.1.6,2 ; master 192.168.1.6, domain 2 You should also set the telecomAnnounce, telecomSync, and telecomDelay values to match what your Telecom master can support. These values are log2n, vice: -3 = eight packets per second -2 = four packets per seconed -1 = two packets per second 0 = one packet per second (recommended value for Sync and Delay) 1 = one packet every two seconds (recommended value for Announce) 2 = one packet every four seconds 3 = one packet every eight seconds The crossCheckMs value is used to determine whether or not dtlinux should use non-PTP sources for sanity checks when PTP timestamps seem to be wrong. If you set this value to zero, then no cross-checking with regular sources will be performed. Otherwise, specify the delta in milliseconds at which PTP should be cross-checked. The meanPathDelayCap value specifies, in microseconds, the maximum delay to which meanPathDelay measurements should be clamped. Set the value to zero to disable the cap. The default is 1500 microseconds, or 1.5 milli- seconds. IEEE 1588 requires that port numbers begin at one. However, if you have a PTP-aware NIC, it may already have claimed the MAC address and port number 1. Change the portNumber below if you have a conflict between this program and a PTP-aware NIC. Otherwise, the specification requires that you leave it at 1. ptp:enabled = true ; if set to false, PTP is disabled ptp:driftRecordsMPD = false ; drift has meanPathDelay vs ppb phase adj ptp:portNumber = 1 ; change this ONLY if you have conflicts ptp:domainNumber = 0 ; range 0-239 (cannot exceed 127 for PTP v2.0) ptp:dynamicDomain = true ; accept any domain? ptp:SdoId = 0xfff ; leave at 0xfff to allow any SdoId ptp:profile = Auto ; must be one of the profile options above ptp:delayTransport = Auto ; use unicast for delay request-response? ptp:crossCheckMs = 25 ; if PTP delta exceeds n ms, cross-check ptp:meanPathDelayCap = 1500 ; Cap meanPathDelay calculations at n micros ptp:utcOffsetOverride = Auto ; specify a TAI-UTC offset, or use Auto ptp:portDSEnabled = true ; Query multicast master for delay frequency ptp:duplicateCheck = true ; check to ensure portIdentity is unique ptp:netSyncMonitor = true ; enable Meinberg NetSync Monitor extensions? ptp:multicastMaster = ; IP or CIDR of authorized PTP multicast master ptp:multicastMaster = ; Add as many as you want, IPv4 or IPv6 ptp:telecomLeaseSecs = 300 ; how many seconds to hold a lease? (30-1000) ptp:telecomAnnounce = 1 ; 2^n frequency of announces (-3 to 3) ptp:telecomSync = 0 ; 2^n frequency of syncs (-3 to 3) ptp:telecomDelay = 0 ; 2^n frequency of delay requests (0 to 3) ptp:telecomMaster = ; Add a Telecom master IP,domain ptp:telecomMaster = ; Add another Telecom master IP,domain [ ----- PTP 1588-2019 (v2.1) Security (optional) -------------------------- ] All PTP v2.1 security works in conjunction with the dtlinux.keys file. PTP v2.1 keys are SHA256, and the algorithm used is HMAC-SHA256-128. PTP v2.1 uses a Security Parameter Pointer (SPP), defined as ptpSPP. The ptpSPP must match what the grandmaster sends, unless ptpSPP is zero, which acts like a wildcard. Entries in your dtlinux.keys file beginning with "ptp" specify keys used for PTP v2.1. Some PTP grandmasters require signed delay requests in in order to generate signed delay responses. Others will sign responses even if the request wasn't signed. Consult your appliance's documentation to determine whether or not to sign outgoing delay requests. If signOutgoingDelay is true, your keyring should contain a ptpDelayReq entry for E2E delay requests, and a ptpPDelayReq entry for P2P delay requests. If these entries don't exist, or don't contain the key number of an SHA256 key in your keyring, then outgoing packets won't be signed. ptpSecurity:enabled = false ; enable v2.1 security? ptpSecurity:preferSignedAnnounces = false ; prefer signed announces? ptpSecurity:requireSignedAnnounces = false ; require signed announces? ptpSecurity:requireSignedSyncs = false ; require signed syncs? ptpSecurity:requireSignedDelayResp = false ; require signed delay responses? ptpSecurity:signOutgoingDelay = false ; sign outgoing delay requests? [ ----- Domain Time II Real-Time Alerts------------------------------------ ] If you are using this program in conjuction with Domain Time II Audit Server, you may configure where Real-Time Alerts are sent, and to which Audit Group this node belongs. Only one of autoAdd and autoDrop may be true. If both are false, the audited status of this node won't be changed. realTimeAlert:enabled = false ; send real-time alerts to Audit Server? realTimeAlert:Target1 = ; IP of primary Audit Server realTimeAlert:Target2 = ; IP of secondary Audit Server realTimeAlert:sendToBoth = false ; send to both Audit Servers? realTimeAlert:auditGroup = 0 ; 0=default, 1-8=group #, 9=no change realTimeAlert:autoAdd = false ; true means always audit this node realTimeAlert:autoDrop = false ; true means never audit this node realTimeAlert:useTCP = false ; send using TCP instead of UDP? [ ----- Domain Time II Security ------------------------------------------- ] You may want to limit access/control by Domain Time II Manager. The default settings allow access from any Manager in the RFC 1918 private network blocks. You may use specific IP addresses, either IPv4 or IPv6, or you may use CIDR masks. Comment out all entries to disallow access entirely. You should allow incoming unicasts and multicasts on port 9909/udp, and in- coming connections on port 9909/tcp. dt2Security:allow = 192.168.0.0/16 ; allow access from 192.168.* dt2Security:allow = 172.16.0.0/12 ; allow access from 172.16.* dt2Security:allow = 10.0.0.0/8 ; allow access from 10.* dt2Security:allow = fe80::0/10 ; allow access IPv6 link-local dt2Security:managerReadOnly = false ; prevent Manager from making changes dt2Security:managerUpgrade = true ; allow Manager to push upgrades? dt2Security:managerRestart = true ; allow Manager to restart service? [ ----- Clock Stepping and Slewing ---------------------------------------- ] Linux-based machines can take a very long time (many hours) to slew a correction that isn't de minimus. Anything over a half-second, forward or backward, can't be slewed directly at all. By default, dtlinux will step after reboot, and will also step the first correction after service restart if the delta is more than a quarter-second. Anything else will slew according to the limits you set below. Stepping at boot is probably required, especially for VMs or machines that don't have a working CMOS clock. The other stepping options are expressed in seconds (max 3600.0, min 0.000001). If you disable stepping altogether, be aware that it may take a *very* long time to achieve synchronization. clock:testModeEnabled makes the service go through all the motions of managing the clock without actually synchronizing the time. It is useful primarily for debugging, or to use the service as a monitor for the steering actions of another time manager. clock:stepAfterReboot = true ; you shouldn't change this clock:stepFirstCorrection = 0.25 ; you shouldn't change this clock:stepSubsequentCorrections = 0.5 ; set to zero to disable other steps clock:stepOnCommandedSync = 0.001 ; okay to step on DTManager command? clock:fastSlewEnabled = true ; run slew at max if delta > 1ms? clock:changeMonitorEnabled = true ; enable clock-change monitor? clock:testModeEnabled = false ; don't change the clock at all [ ----- Advanced Sample Filtering ----------------------------------------- ] There are a number of filters you can engage to help filter time samples to detect outliers. You should pretty much leave these at the default settings, because the standard analytics do a better job of estimating the group population. Popcorn will discard the two most extreme samples, as long as you have three or more samples to choose from. Be especially careful with filter:maxDelayMs. It discards ALL samples whose round-trip time (the latency, or delay) exceeds the number of milliseconds you specify. This may result in no useable samples left at all. filter:Popcorn = true ; discards hi-lo samples filter:Stratum = false ; discards all but the lowest stratum samples filter:Delay = false ; discards samples with highest latency filter:Delta = false ; discards samples with the highest deltas filter:maxDelayMs = 0 ; if non-zero, this is the max latency in ms [ ----- Miscellaneous Variables ------------------------------------------- ] This section is reserved for uncategorized, miscellaneous, or new settings. Anything that does not belong elsewhere goes here. On multiprocessor machines when misc:SetAffinity is true, dtlinux will split up tasks intelligently to reduce cache-line misses. If it is false, then dtlinux will allow the kernel scheduler to assign processors. If misc:KernelLeapSeconds is true, then dtlinux will schedule leap-second handling to occur at UTC midnight using the kernel functions. If it is false, then dtlinux will ignore advance notice of pending leaps, and deal with the discontinuity after the leap second has occurred, just as it would with any other unexpected change. If misc:updateURL is not blank, it will override the pre-defined upstream source used to check for updates. The format must be http[s]://server[:port]/path/ ##! Do not remove or alter this line (miscellaneous) !## misc:SetAffinity = true ; enable processor affinity? misc:KernelLeapSeconds = true ; enable kernel handling of leap seconds? misc:updateURL = ; alternate source for updates [ ----- Firewall Advice --------------------------------------------------- ] Firewall requirements are documented in the dtlinux(8) man page. Please read that for complete information. Some protocols use fixed source and target ports, while others use ephemeral source ports with fixed target ports. You may restrict the range of ephemeral ports used for outgoing time requests by changing network:sourcePortUDP above. Make sure that the port range you select does not conflict with any well-known services. If network:sourcePortUDP is zero, the operating system will select an ephemeral port. If it is non-zero, it indicates the start of a range of five ports beginning with the port number you specify. For example, if you use network:sourcePortUDP=3333, then dtlinux will attempt to send from port 3333. If 3333 is already in use, it will try 3334, and so on, for up to five ports. If none of the ports in the range you specify are available, then the bind (and transaction) will fail. The range is required because multiple threads may be trying to sending unicast requests at the same time. NOTE: network:sourcePortUDP only applies to NTP and DT2 UDP-based protocols. TCP will always use an ephemeral source port, and PTP will always use fixed ports 319/udp and 320/udp. [ ----- License: Commercial Proprietary (registration required) ----------- ] This program is delivered as an evaluation version. You may use it for up to 30 days for testing. If you want to continue using it after that, you must obtain a registration code from your vendor. The registration code will look something like this: 692310601-94007843. The number of digits may vary. To register your program, run the following command as root or sudo: dtlinux -registration=692310601-94007843 Use the real code provided by your vendor, not the example code shown above. NOTE: You can also send the registration code from a Windows machine, using either DTCheck or Domain Time II Manager. If you use Manager, you may register multiple machines at the same time. If you perform an upgrade, you will not need to re-register. [ ----- Always leave at least one blank line at the end ------------------- ]