NTP management scripts

I've been participating in the NTP pool project since July 2003, and during this time, I've developed a few scripts to help monitor and manage NTP stuff. I figure that these scripts might be useful to others, so I'm posting them here, but please don't expect anything fancy. The documentation is bad, there are few comments, and they haven't been tested on any machine other than mine. Feel free to use the scripts for anything you want. They are in the public domain.

I recommend getting at least ntp_clients, ntp_clients_stats, and ntp_pool_dns. These can all be downloaded via ntp_scripts.tar.gz.

NTP Client monitoring scripts

The ntpdc program has a "monlist" command which will list information the ntp clients that your ntpd server has been monitoring. While this is useful in some case, it has the following problems:

• A maximum of 600 clients can be monitored, which almost all NTP pool servers probably exceed. Once you come close to this limit, much of the information becomes useless.
• The format changed between v4.1.x and v4.2.x, making portable script writing harder.
• At least with my debian 4.2.0a version of ntpdc, the command frequently errors out if you come close to the 600 client limit.

As a result, I've written the following scripts which use tcpdump to gather information, rather than the monlist command. In addition, there is a lot more statistical analysis done one the clients.

ntp_clients (perl)

This script use tcpdump to gather statistics about ntp clients. It will then report information about the clients as it sees new packets, and/or write a summary of all recent clients to a "dump file" (depending on the options given). The dump file can be used either when restarting ntp_clients, or by ntp_clients_stats.

The options are:

  Usage: ntp_clients [options]
  
        -help	Help on the options.
  
        -dumpfile=/path/dumpfile  File to read/write internal state
        -startfile=/path/dumpfile File to read initial state
        -interface=eth#           Lan interface to monitor\n";
        -verbose                  increase amount of information printed
                                  by default, track only bad clients
                                  -v will give you all clients
                                  -v -v will give you all requests
        -tcpdump=version          set format of NTP trace output
        -quiet                    don't print any info
        

Example output:

     Time      Total     Num      Client         Client    Delta    Rate
             Requests  Clients      IP          Requests   (sec)    (sec)
   18:14:21   4998193    1497  134.231.11.189      19407    +73.0     4.62
   18:14:21   4998194    1497  128.233.169.96       8495    +78.4    14.55
   18:14:22   4998197    1497  207.173.206.5      217276    +76.0     8.82
   18:14:22   4998199    1497  82.182.139.38       32052    +92.1    33.17
   18:14:24   4998206    1497  24.243.14.116        4591    +90.4    32.72
   18:14:25   4998209    1497  80.176.211.45       34764    +90.7    33.24
   18:14:25   4998212    1497  67.64.154.225       26396    +91.1    33.09
   18:14:25   4998213    1497  136.200.128.196     18010    +80.0    19.20
   18:14:27   4998220    1497  64.19.16.106        87947   +121.2    16.40
        

Since it takes several hours before enough data can be collected to generate good statistics, I recommend running the following command at the ntpd startup, and keep it running.

  ntp_clients -dump /var/www/ntpstats/ntp_stats.dump >>/var/www/ntpstats/ntp_stats.log 2>&1 &
        

I also recommend having the following entry in your root's crontab:

   */5   *   * * *   /usr/local/sbin/ntp_pool_dns >>/var/www/ntpstats/pool_stats.log
   1     *   * * *   /usr/local/sbin/ntp_stats_archive
        

Note that, as per the recommendations above, information about your ntp clients will be put into your public website. Since the information released is basically the same as is already released by the monlist command, this should not be a problem for most people. However if, for some reason, you have disabled the monlist command in your ntp.conf, you probably want to change the above defaults.

ntp_clients_stats (perl)

This script generates statistics about the data collected by ntp_clients and written to a dump file. For details, see the current stats for my ntp server.

ntp_stats_archive (portable shell script)

This script archives a selection of dump files so that they can be analyzed later to spot trends and such.

ntp_pool_dns (portable shell script)

This script uses the ntp_client_stats script to generate a one line summary of the current number of NTP clients, the number of abusive NTP clients, and it also determines how many times your NTP daemon is listed in the current NTP Pool DNS.

An example result is:

   03/05/05 16:35:13  1011  22   2 aventura.bhms-groep.nl zbasel.fortytwo.ch
        

This says that at 03/05/05 16:35:13, there were 1011 active ntp clients, of which 22 were "abusive". My ntp server was found in two of the half-dozen or so pool name servers.

Since the output is very short, this script is useful for accumulating long term data about the clients. (See the crontab entry mentioned above.)

NTP daemon sanity checker scripts

calc_ntp_good (bash shell script)

This script grunges through your ntp logs and calculates a "good" value for your /var/lib/ntp/ntp.drift file. While ntp will update this file for you, calc_ntp_good looks over a much longer term, selecting only the best values from when the ntp daemon is running well.

reset_ntp (bash shell script)

This script looks to see if the ntpd is too far out of sync with the true time and has therefore munged the ntp.drift value too much. While ntpd will eventually get back to normal all by itself, it is generally *MUCH* quicker to reset the drift file to a known good value (as found by calc_ntp_good), and restart ntpd.

This is most useful for things like laptops, which are not connected all the time and have power saving modes mess up the real time clock. I happen to run it on my pool server also, and it rarely does anything. Sometimes it will reset the ntpd when my pipe has been saturated by a long, very large download, or something.

If you want to use these scripts, I recommend having the following entry in your root's crontab:

   26    *   * * *   /usr/local/sbin/calc_ntp_good -u  >>/var/log/ntpstats/good.log 2>&1
   */5   *   * * *   /usr/local/sbin/reset_ntp >>/var/log/ntpstats/reset.log 2>&1
        

Scripts for looking at other NTP pool servers

These are older scripts that aren't as portable or as functional as the scripts mentioned above, except for one feature: They can tell you about other ntp servers than the ones you control.

ntp_pool (bash shell script)

keeps track of how many ntp clients a give server has. If the verbose option (-v) is given, it will also display a list of clients that may be abusing the server, either by having many clients from the same subnet using the server, or by having very short poll times.

ntp_pool_stats (bash shell script)

This script calls ntp_pool, but also checks to see if the server is listed in any of the pool.ntp.org name servers.

xntpdc (bash shell script)

For some reason, my debian 4.2.0a ntpdc command frequently times out with an "Response from server was incomplete" message. This script just keeps retrying until it gets an answer.