contrib/ntp/scripts/monitoring/README

   1 This directory contains support for monitoring the local clock of xntp daemons.
   2
   3 WARNING: The scripts and routines contained in this directory are beta
   4          release!  Do not depend on their correct operation. They are,
   5          however, in regular use at University of Erlangen-Nuernberg.
   6          No severe problems are known for this code.
   7
   8 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   9 PLEASE THINK TWICE BEFORE STARTING MONITORING REMOTE XNTP DEAMONS !!!!
  10 MONITORING MAY INCREASE THE LOAD OF THE DEAMON MONITORED AND MAY
  11 INCREASE THE NETWORK LOAD SIGNIFICANTLY
  12 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  13
  14
  15 Files are:
  16
  17 README:
  18         This file
  19
  20 ntptrap:
  21         perl script to log ntp mode 6 trap messages.
  22
  23         It sends a set_trap request to each server given and dumps the
  24         trap messages received. It handles refresh of set_trap.
  25         Currently it handles only NTP V2, however the NTP V3 servers
  26         also accept v2 requests. It will not interpret v3 system and
  27         peer stati correctly.
  28
  29         usage:
  30           ntptrap [-n] [-p <port>] [-l <debug-output>] servers...
  31
  32         -n:             do not send set_trap requests
  33
  34         port:           port to listen for responses
  35                         useful if you have a configured trap
  36
  37         debug-output:   file to write trace output to (for debugging)
  38
  39         This script convinced me that ntp trap messages are only of
  40         little use.
  41
  42 ntploopstat:
  43         perl script to gather loop info statistics from xntpd via mode 7
  44         LOOP_INFO requests.
  45
  46         This script collects data to allow monitoring of remote xntp servers
  47         where it is not possible to directly access the loopstats file
  48         produced by xntpd itself. Of course, it can be used to sample
  49         a local server if it is not configured to produce a loopstats file.
  50
  51         Please note, this program poses a high load on the server as
  52         a communication takes place every delay seconds ! USE WITH CARE !
  53
  54         usage:
  55           ntploopstat [-d<delay>] [-t<timeout>] [-l <logfile>] [-v] [ntpserver]
  56
  57         delay:          number of seconds to wait between samples
  58                         default: 60 seconds
  59         timeout:        number of seconds to wait for reply
  60                         default 12 seconds
  61         logfile:        file to log samples to
  62                         default: loopstats:<ntpserver>:
  63                         (note the trailing colon)
  64                         This name actually is a prefix.
  65                         The file name is dynamically derived by appending
  66                         the name of the month the sample belongs to.
  67                         Thus all samples of a month end up in the same file.
  68
  69         the format of the files generated is identical to the format used by
  70         xntpd with the loopstats file:
  71                 MJD <seconds since midnight UTC> offset frequency compliance
  72
  73         if a timeout occurs the next sample is tried after delay/2 seconds
  74
  75         The script will terminate after MAX_FAIL (currently 60)
  76         consecutive errors.
  77
  78         Errors are counted for:
  79                 - error on send call
  80                 - error on select call
  81                 - error on recv call
  82                 - short packet received
  83                 - bad packet
  84                 - error on open for logfile
  85
  86 ntploopwatch:
  87         perl script to display loop filter statistics collected by ntploopstat
  88         or dumped directly by xntpd.
  89
  90         Gnuplot is used to produce a graphical representation of the sample
  91         values, that have been preprocessed and analysed by this script.
  92
  93         It can either be called to produce a printout of specific data set or
  94         used to continously monitor the values. Monitoring is achieved by
  95         periodically reprocessing the logfiles, which are updated regularly
  96         either by a running ntploopstat process or by the running xntpd.
  97
  98         usage:
  99           to watch statistics permanently:
 100              ntploopwatch [-v[<level>]] [-c <config-file>] [-d <working-dir>]
 101
 102           to get a single print out specify also
 103                           -P<printer> [-s<samples>]
 104                                       [-S <start-time>] [-E <end-time>]
 105                                       [-O <MaxOffs>] [-o <MinOffs>]
 106
 107         level:          level of verbosity for debugging
 108         config-file:    file to read configurable settings from
 109                         On each iteration it is checked and reread
 110                         if it has been changed
 111                         default: loopwatch.config
 112         working-dir:    specify working directory for process, affects
 113                         interpretation of relative file names
 114
 115         All other flags are only useful with printing plots, as otherwise
 116         command line values would be replaced by settings from the config file.
 117
 118         printer:        specify printer to print plot
 119                         BSD print systems semantics apply; if printer
 120                         is omitted the name "ps" is used; plots are
 121                         prepared using PostScript, thus the printer
 122                         should best accept postscript input
 123
 124         For the following see also the comments in loopwatch.config.SAMPLE
 125
 126         samples:        use last # samples from input data
 127         start-time:     ignore input samples before this date
 128         end-time:       ignore input samples after this date
 129                         if both start-time and end-time are specified
 130                         a given samples value is ignored
 131         MaxOffs:
 132         MinOffs:        restrict value range
 133
 134 loopwatch.config.SAMPLE:
 135         sample config file for ntploopwatch
 136         each configurable option is explained there
 137
 138 lr.pl:
 139         linear regression package used by ntploopwatch to compute
 140         linear approximations for frequency and offset values
 141         within display range
 142
 143 timelocal.pl:
 144
 145         used during conversion of ISO_DATE_TIME values specified in
 146         loopwatch config files to unix epoch values (seconds since
 147         1970-01-01_00:00_00 UTC)
 148
 149         A version of this file is distributed with perl-4.x, however,
 150         it has a bug related to dates crossing 1970, causing endless loops..
 151         The version contained here has been fixed.
 152
 153 ntp.pl:
 154         perl support for ntp v2 mode 6 message handling
 155         WARNING: This code is beta level - it triggers a memory leak;
 156                  as for now it is not quite clear, wether this is caused by a
 157                  bug in perl or by bad usage of perl within this script.
 158