README revision 54359 
1This directory contains support for monitoring the local clock of xntp daemons.
2
3WARNING: The scripts and routines contained in this directory are bete realease!
4	 Do not depend on their correct operation. They are, however, in regular
5	 use at University of Erlangen-Nuernberg. No severe problems are known
6	 for this code.
7
8!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
9PLEASE THINK TWICE BEFORE STARTING MONITORING REMOTE XNTP DEAMONS !!!!
10MONITORING MAY INCREASE THE LOAD OF THE DEAMON MONITORED AND MAY
11INCREASE THE NETWORK LOAD SIGNIFICANTLY 
12!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
13
14
15Files are:
16
17README:
18	This file
19
20ntptrap:
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 peer
27	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
42ntploopstat:
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) consecutive errors.
76	Errors are counted for:
77		- error on send call
78		- error on select call
79		- error on recv call
80		- short packet received
81		- bad packet 
82		- error on open for logfile
83
84ntploopwatch:
85	perl script to display loop filter statistics collected by ntploopstat
86	or dumped directly by xntpd.
87
88	Gnuplot is used to produce a graphical representation of the sample
89	values, that have been preprocessed and analysed by this script.
90
91	It can either be called to produce a printout of specific data set or
92	used to continously monitor the values. Monitoring is achieved by 
93	periodically reprocessing the logfiles, which are updated regularly
94	either by a running ntploopstat process or by the running xntpd.
95
96	usage:
97	  to watch statistics permanently:
98	     ntploopwatch [-v[<level>]] [-c <config-file>] [-d <working-dir>]
99
100	  to get a single print out specify also
101			  -P<printer> [-s<samples>]
102				      [-S <start-time>] [-E <end-time>]
103				      [-O <MaxOffs>] [-o <MinOffs>]
104	
105	level:		level of verbosity for debugging
106	config-file:	file to read configurable settings from
107			On each iteration it is checked and reread
108			if it has been changed
109			default: loopwatch.config
110	working-dir:	specify working directory for process, affects
111			interpretation of relative file names
112	
113	All other flags are only useful with printing plots, as otherwise
114	command line values would be replaced by settings from the config file.
115
116	printer:	specify printer to print plot
117			BSD print systems semantics apply; if printer is omitted
118			the name "ps" is used; plots are prepared using
119			PostScript, thus the printer should best accept
120			postscript input
121
122	For the following see also the comments in loopwatch.config.SAMPLE
123
124	samples:	use last # samples from input data
125	start-time:	ignore input samples before this date
126	end-time:	ignore input samples after this date
127			if both start-time and end-time are specified
128			a given samples value is ignored
129	MaxOffs:
130	MinOffs:	restrict value range 
131
132loopwatch.config.SAMPLE:
133	sample config file for ntploopwatch
134	each configurable option is explained there
135
136lr.pl:
137	linear regression package used by ntploopwatch to compute
138	linear approximations for frequency and offset values
139	within display range
140
141timelocal.pl:
142	used during conversion of ISO_DATE_TIME values specified in loopwatch
143	config files to unix epoch values (seconds since 1970-01-01_00:00_00 UTC)
144
145	A version of this file is distributed with perl-4.x, however,
146	it has a bug related to dates crossing 1970, causing endless loops..
147	The version contained here has been fixed.
148
149ntp.pl:
150	perl support for ntp v2 mode 6 message handling
151	WARNING: This code is beta level - it triggers a memory leak;
152		 as for now it is not quite clear, wether this is caused by a
153		 bug in perl or by bad usage of perl within this script.
154
155