troglobit/sntpd

sntpd is a fork of Larry Doolittle's ntpclient with added daemon, syslog, and IPv6 support

sntpd

Table of Contents

• Introduction
• Usage
• Troubleshooting
• Bugs
• Compliance
• Building
• Building from GIT
• Origin & References

Introduction

sntpd is a small SNTP server and client for UNIX systems, implementing RFC 1305 and RFC 4330. Its functionality is only a small subset of ntpd, chrony, OpenNTPd, and xntpd. Since it is much smaller it is also more relevant for embedded systems in need of only a background process to keep the system time in sync (client mode).

sntpd is a fork of ntpclient by Larry Doolittle. As such it implements a compatibility mode when called with the name ntpclient. The name has been changed to indicate the expanded feature set, e.g. a background daemon mode, IPv6, syslog, as well as changes in command line options.

Use the GitHub issue tracker to report bugs. If you want to contribute fixes or new features, see the file CONTRIBUTING.md.

Note: sntpd has limited support for acting as an SNTP server. The server mode is enabled by default, disable with -p 0.

Usage

All arguments are optional, sntpd defaults to use pool.ntp.org.

Usage:
  sntpd [options] [SERVER]

  -d       Dry run, no time correction, useful for debugging
  -h       Show summary of command line options and exit
  -i SEC   Check time every interval seconds.  Default: 600
  -l LEVEL Set log level: none, err, warn, notice (default), info, debug
  -n       Don't fork.  Prevents sntpd from daemonizing by default
           Use '-s' with this to use syslog as well, for Finit + systemd
  -p PORT  SNTP server mode port, default: 123, use 0 to disable
  -q USEC  Minimum packet delay for transaction, default: 800 usec
  -s       Use syslog instead of stdout, default unless -n
  -t       Trust network and server, disable RFC4330 validation
  -v       Show program version

  SERVER   Optional NTP server to sync with, default: pool.ntp.org

Compatibility

The sntpd project comes with a compatiblity mode triggered when called as ntpclient. This mode supports the original command line options.

Mortal users can use the ntpclient tool for monitoring, but not clock setting (with the -s or -l switches). The -l switch is designed to be robust in any network environment, but has seen the most extensive testing in a low latency (less than 2 ms) Ethernet environment. Users in other environments should study sntpd's behavior, and be prepared to adjust internal tuning parameters. A long description of how and why to use sntpd and ntpclient is in the HowTo.md file. sntpd always sends packets to the server's UDP port 123.

One commonly needed tuning parameter for lock mode is min_delay, the shortest possible round-trip transaction time. This can be set with the command line -q switch. The historical default of 800 microseconds was good for local Ethernet hardware a few years ago. If it is set too high, you will get a lot of "inconsistent" lines in the log file when time locking (-l switch). The only true future-proof value is 0, but that will cause the local time to wander more than it should. Setting it to 200 is recommended on an end client.

The test.dat file that is part of the source distribution has 200 lines of sample output. Its first few lines, with the output column headers that are shown when the -d option is chosen, are:

  day    second   elapsed    stall      skew  dispersion  freq
36765 00180.386    1398.0     40.3  953773.9       793.5  -1240000
36765 00780.382    1358.0     41.3  954329.0       915.5  -1240000
36765 01380.381    1439.0     56.0  954871.3       915.5  -1240000

• day, second: time of measurement, UTC, relative to NTP epoch (Jan 1, 1900)
• elapsed: total time from query to response (microseconds)
• stall: time the server reports that it sat on the request (microseconds)
• skew: difference between local time and server time (microseconds)
• dispersion: reported by server, see RFC 1305 (microseconds)
• freq: local clock frequency adjustment (Linux only, ppm*65536)

ntclient performs a series of sanity checks on UDP packets received, as recommended by RFC 4330. If it fails one of these tests, the line described above is replaced by 36765 01380.381 rejected packet or, if --enable-debug was selected at configure, one of:

36765 01380.381  rejected packet: LI==3
36765 01380.381  rejected packet: VN<3
36765 01380.381  rejected packet: MODE!=3
36765 01380.381  rejected packet: ORG!=sent
36765 01380.381  rejected packet: XMT==0
36765 01380.381  rejected packet: abs(DELAY)>65536
36765 01380.381  rejected packet: abs(DISP)>65536
36765 01380.381  rejected packet: STRATUM==0

To see the actual values of the rejected packet, start the ntpclient tool or sntpd with the -d option; this will give a human-readable printout of every packet received, including the rejected ones. To skip these checks, use the -t switch.

The file test.dat is suitable for piping into ntpclient -r. There are more than 200000 samples (lines) archived for study. They are generally spaced 10 minutes apart, representing over three years of data logging (from a variety of machines, and not continuous, unfortunately). If you are interested, contact Larry.

Also included is a version of the adjtimex(1) tool. See its man page and the HowTo.md file for more information.

Another tool is envelope, which is a perl script that was used for the lock studies. It's kind of a hack and not worth documenting here.

Troubleshooting

Some really old Linux systems (e.g., Red Hat EL-3.0 and Ubuntu 4.10) have a totally broken POSIX clock_settime() implementation. If you get the following with sntpd -s:

clock_settime: Invalid argument

then configure --enable-obsolete. Linux systems that are even older will not even compile without that switch set.

Bugs

• Doesn't understand the LI (Leap second Indicator) field of an NTP packet
• Doesn't interact with adjtimex(2) status value
• Cannot query multiple servers
• Requires Linux select() semantics, where timeout value is modified

Compliance

Adherence to RFC 4330 chapter 10, Best practices:

1. Enforced, unless someone tinkers with the source code
2. No backoff, but no retry either; this isn't TCP
3. Not in scope for the upstream source
4. Defaults to pool.ntp.org, but is configurable
5. Not in scope for the upstream source
6. Supported
7. Supported, connection to server reopened once a day
8. Not supported (scary opportunity to DOS the client)

Building

Please use released, and versioned, tarballs of this project. All releases are available from here:

☞ https://github.com/troglobit/sntpd/releases

sntpd uses the GNU configure & build system:

    ./configure
    make

The GNU build system use /usr/local as the default install prefix. In many cases this is useful, but many users expect /usr or /opt. To install into /usr/sbin/sntpd and /usr/bin/adjtimex:

    ./configure --prefix=/usr
    make
    sudo make install-strip

The last command installs, there is also a possiblity to uninstall all files using:

    sudo make uninstall

For changing the system clock frequency, only the Linux adjtimex(2) interface is implemented at this time. Non-Linux systems can only use the ntpclient tool to measure time differences and set the system clock, by way of the POSIX 1003.1-2001 standard, the routines clock_gettime() and clock_settime(). Also, see section Bugs, below.

There are a few compile-time configurations possible. E.g., for older Linux kernels, before the tickless erea (pre 3.0), you want to:

    ./configure --disable-siocgstamp

However, first try without changing the default. That gives you a full- featured sntpd and ntpclient tool that use a modern POSIX time API and works reasonably well with any Linux kernel.

Solaris and other UNIX users may need to adjust the CFLAGS slightly. For other options, see ./configure --help

Building from GIT

If you want to contribute, or try out the latest unreleased features, here is a few things to know about GNU build system:

• configure.ac and a per-directory Makefile.am are key files
• configure and Makefile.in are generated from autogen.sh, they are not stored in GIT but automatically generated for the release tarballs
• Makefile is generated by configure script

To build from GIT you first need to clone the repository and run the autogen.sh script. This requires automake and autoconf to be installed on your system.

    git clone https://github.com/troglobit/sntpd.git
    cd sntpd/
    ./autogen.sh
    ./configure && make

Remember: GIT sources are a moving target and not recommended for production systems, unless you know what you are doing!

Origin & References

Larry Doolittle created ntpclient and made it freely available under the terms of the GNU General Public License, version 2. He remains the official upstream for ntpclient.

This sntpd fork at GitHub is maintained by Joachim Wiberg and adds features like syslog, background daemon, IPv6, and systemd support.

sntpd's Issues

Use IPV4 if IPV6 is present and disabled.

When booting a Linux system with the kernel command line option:
ipv6.disable=1 the IPV6 kernel module will be loaded but administratively disabled.
If I try to use ntpclient 2017.246 on such a system to set the time and exit:
ntpclient -dstvn pool.ntp.org
I get
ERROR - Failed creating UDP socket() to SNTP server: Address family not supported by protocol
Booting without this option eliminates the issue.

same argument for o1 and o2

In rate.awk FNR is used to read only one record. o1 and o2 has same argument $5.For same record argument will be the same .slop is using calculation o1 subtracting from o2 .It will be always zero.

compatibility with upstream and usermode

I'm using ntpclient to monitor the clock offset of a bunch of machines.

With the original ntpclient version, I could easily get this information (root or not):

root$ ntpclient -c1 -h pool.ntp.org
43441 60350.979    1963.0      5.9     890.3  21179.2     11344

In troglobit's fork, '-h' was changed to mean 'help' and the output goes to stderr (why?) so I have to adjust a few flags and redirect the output to stdout. It broke out of the box compatibility with the old version, but so far I can still live with that (as non root):

nobody$ ntpclient -c1 pool.ntp.org 2>&1
43441 58627.120    2270.0      8.3      27.8  63232.4     66222

Now the problem arises when I want to do the same thing as root. First, I need to disable daemon mode, which is enabled by default for root 😞. However, this still does not work! When running as root, the output is disabled and I need to enable debug mode to see anything (which also adds other unwanted messages):

root$ ntpclient -c1 -n -d pool.ntp.org 2>&1
packet of length 48 received
43441 59793.248    2063.0     34.0    5109.1  42770.4     -4915

To make it worse, the only way I could find this was by looking at the code:

https://github.com/troglobit/ntpclient/blob/435e52063a863e1b1ef0463f78cb1b156cd1bd00/src/ntpclient.c#L477-L483

That being said, I have two suggestions to solve this:

• add a usermode flag, so useful output can be seen without enabling debug mode, or
• turn the output on when verbose mode is enabled (instead of debug). This is probably better, since providing a probe count already disables live mode and enables verbose mode:
  https://github.com/troglobit/ntpclient/blob/435e52063a863e1b1ef0463f78cb1b156cd1bd00/src/ntpclient.c#L989-L993

TL;DR: this fork adds a daemon mode to ntpclient, but almost breaks its original purpose. It would be good to not assume behaviour based on the EUID or to at least introduce a 'usermode' flag.

I don't mind preparing a pull request after getting some feedback on this.