		MONITOR
		-------
PURPOSE:
	A Web-based monitoring program written in Perl, designed to
watch designated hosts and printers using ping, traceroute, rup, and
standard printer status facilities.

LEGAL STUFF:
	If you think Monitor will help you, fine.  If you get in
trouble using it, tough.  Use at your own risk.  I am not liable if
Monitor crashes your system, eats your disk, or any other unexpected
thing.  No matter how much fun it may be to sue me, you can't.
	If you want to copy it, do so, just retain all of my source in
what you distribute.  Any distribution of it can take place, in its
unmodified form.
	'Nuff said.

INSTALLATION:

	If you are root on the machine it is going onto, you will
probably want to untar the package into /usr/local/monitor or
something like that.  Also, you'll want to think about whether you
want Monitor run as a cron job (the only way to run 0.1alpha), or as a
daemon (0.2alpha and later) and which userid you'd like it to run as.
I would probably recommend creating a non-loginable account named
"www", and configuring your httpd to run as userid "www".  That way,
you can configure Monitor to dump its output to the httpd home, or a
subdirectory of it, and not have to worry any about permissions.  I
would probably also recommend setting it up so that whatever directory
points to http://your.web.server/monitor/ is the directory that output
shows up in.  It's easier to let people on the net see the Monitor
output with a simple-to-remember path than with a longer one.  By the
same token, if you want it on the web for your own purposes, but don't
want it *too* easily remembered, nest it as deeply as you like.
	If you are not root, and wish to run this out of your own
account, I would recommend making a directory named ~/monitor and
configuring it to put its output into your ~/public_html/monitor
directory (you should replace "public_html" with whatever directory
name your system administrator told you is your own "public" area).
	In either case, make sure that you chmod the output directory
so that the userid running Monitor can both read and write to that
directory.  Note that this also means setting the "x" bit (chmod
0755).
	Once you've unpacked Monitor to where it is going to live,
create the directory that its output is going to reside in, and where
output will be archived to.  Copy the monitor.gif file into the main
output directory, so that it is visible to the web.  I would probably
root the archive tree inside the output directory, and chmod it 0755
so that it is readable by the web.  That way, when you want to view
the past output of Monitor, it is available for quick, remote perusal.
	However, as a precautionary notice, it may be good to note
that each host you generate an HTML file for will cost about 1.3kb to
1.5kb of disk space.  This may not sound like much, but multiply that
by, say 10 hosts, run once an hour for a month.  That's 10M or so.  If
you have everything archived to a partition that doesn't have a whole
lot of space on it, you could be running up against some contraints.
If *possible* (I'm not really recommending this, but if you use
Monitor often, you may want to think about this) you may want to have
the archive directory specifying a separate partition, so that your
system areas aren't getting filled with Monitor output.  Most people
might thing something like /var/logs would be a good place to archive
it, but also not that a lot of people make /var either a part of their
root directory or on a small partition (10M to 30M, often).  Just
something to think about.
	This much should do it for the installation section.  Now that
you have the files & directories you need, we move along to
configuration.

CONFIGURATION:

	The first thing you want to do is edit the file monitor.loc.
This contains the absolute path of the monitor.conf file.  Next, move
monitor.loc to /etc.  If that isn't possible (if you're not root),
then modify the source of "monitor" and change the line in the
beginning that says '$root = "/etc"' to point to where ever you decide
to put it.  Just don't modify anything else in there!  Then, modify
monitor.conf to reflect the way your machine is set up.  Hopefully,
within the next few releases, I will have a configuration script that
will do the dirty work for you, and let you just sit back and let it
figure out where stuff is.  But for now, you'll have to do it all by
hand.
	If you're installing it onto a Slackware 3.2 (Infomagic April
'97 CD set) or most other similar Linux installations, most of the
parameters will be configured correctly already.  However, if you are
installing this into some other unix system (Solaris, SunOS, Irix,
HP-UX, NetBSD, FreeBSD, SCO, etc.) you'll need a bit more familiarity
with your own system to know where exactly stuff goes.  But in
general, you shouldn't have *too* much trouble.  Using the "where"
command in tcsh or "whereis" command will aid in pointing parameters
at the appropriate locations.  The following is the meaning of each of
these configurable parameters:

log
	This points to where you'd like to see the log info go.  I
would hesitate to put this in a file that is viewable by the web.
With it, hackers could potentially find the weaknesses of your system,
or another system.  Sending it to /usr/local/monitor/log/monitor.log,
and keeping that info to yourself is probably a good idea.  In it will
be information about when a process started, any exit code it may have
produced, or other info.  It's good for debugging things if you find
an error in how things are set up.

tmp
	This is a directory that can be written to for temporary
storage.  Raw data is generally dumped into this region in the
preparation of the HTML.  For example, the "ping" commands will dump
their output into files in the "tmp" directory, then wrap each file in
HTML and post it to the web-visible directory.  Future releases of
Monitor will clean the "tmp" directory judiciously, but for now things
that get dumped into "tmp" will stay there until they are manually
removed.

route
	The command which produces the local routing table.  Note that
this should probably be output in raw IP form, ie using "route -n" for
numeric display.  Sometimes, especially in systems which are
gatewaying IP packets and forwarding them to other networks
(specifically, Linux machines set up as routers or ip_masquerading
boxes for localnet to Internet proxy connections) will not be able to
ascertain hostnames directly from the routing tables.  In this case,
route will hang, and you'll probably get meaningless output from
route.  Using the "-n" switch will give you the IP of the route,
rather than letting route try and figure out the hostname, which
simply may not be accessible.

ping
	This should yield a single, or at least regulated, set of ping
statistics.  Under Solaris/SunOS and other flavors of unix, the usual
"ping hostname" will simply yield "hostname is alive".  However, under
Slackware Linux, ping will loop infinitely, and the "-c" parameter
must be used.  I recommend a number under 10 to be passed to the "-c"
parameter, otherwise you may get excessive output.  Most systems, if
they are having a problem, will die on at least 1 out or 10 pings.
You can make a case for pinging a host 500 times in a row, but one
thing is sure: DON'T LET IT BE INFINITE! ... or you'll never get to
see the output of the ping!

hthome
	This is the location of the HTML to be generated by Monitor.
It should be world readable and writable by the "monitor" task, meaning
having a mode of something like 0755.  

email (optional)
	This lets you specify someone who will be the monitor
contact.  It could be any valid email address.  If someone is viewing
the output of monitor, and spots something you should know about, you
should have the ability to receive email instantly about that
problem.  This will be in the form of a "mailto:" at the bottom of
each HTML page.

index
	Most httpd's are configured in such a way so that they
automatically hand over a file named "index.html", if it exists in a
web-viewable directory, when no explicit filename is specified.
However, other systems may not be configurable like that, or may have
it set to some other file name.  This lets you specify which filename
gets automatically handed over, so that when someone goes to
http://your.web.server/monitor (or where ever you decide to put the
directory), they are automatically greeted with the Monitor welcome
page.

update (not implemented in 0.1alpha)
	This will allow you to set the frequency, in minutes, of when
to update the Monitor output.  This is only useful to Monitor when it
is being run in daemon mode without the "once" parameter on the
command line.

date
	The command that yields a human-readable form of the date
should be placed here.  On some systems, it is /usr/bin/date, on
others it is /bin/date, and maybe some other location on others.  This
lets you configure where it is located.

delete
	This specifies the location of the system-level command that
deletes files.  This is used when removing the temporary files located
in "tmp".

syslog (not implemented in 0.1alpha and 0.2alpha)
	This is an additional logging facility that will let you
specify where logging information should go.  The necessity of this
(as opposed to just using "log") is not yet determinable.

traceroute
	In order to make sure that systems which you depend on that
are not local to you are up (news, mail, etc.) and are routing traffic
as expected, it's important to be able to traceroute to them.  Also,
this is good for making sure that your ISP (and *their* ISP) is
keeping traffic flowing in a nice manner.  

sys (not fully implemented in 0.1alpha or 0.2alpha)
	This allows you to specify whether you are running on a Linux
system, or on a Windows95/NT system.  There are 2 values it can be set
to: Linux of Win95+.  Monitor 0.1alpha is a unix/Linux-only program,
and only (much) later releases will have portability to Win95 or NT.

directory
	This should point to the command that lists the files in the
current directory, with no additional information.  Note that there
should be no file sizes, dates, or anything other than the filenames
themselves in the output of this command.

ruptime (and ruptime2) (optional)
	These commands are used for determining the load on remote
systems.  Since many systems (including Slackware Linux) do not come
with such a facility (like Sun's RPC "rup" command), this is
configurable to use 2 different commands, "ruptime" and "ruptime2".
Most likely, in a heterogeneous network, you'll have machines that
will respond to "rup" calls, and machines that won't.  Supplied with
this package are Perl scripts called "ruptime" and "ruptimed".
Ruptimed is a server which reports the hostname and uptime load to TCP
port 777, and ruptime is a client which opens port 777 on a remote
machine and reads until the port is closed.  If you find a problem
with using port 777, let me know, and tell me what conflicts with it.
Feel free to change the port in both "ruptimed" and "ruptime" if you
like.

ifconfig
	To know what your ethernet devices are thinking, the best
thing to do is ifconfig them and see what you get.  This command
should output a full (or selective, if you want to ignore some
interfaces) list of the network interfaces available, their IP
addresses, netmasks, packet statistics, and other info that would be
useful in determining if your machine is ok.  The usual "ifconfig"
under Linux is quite acceptable.  Solaris/SunOS machines that need
an interface name for each invocation of ifconfig, will not work with
this out-of-the-box if there is more than 1 ethernet device.  But then
again, I'm not sure if I want to support those platforms.  

prnstat
	This command should be set to something that will determine
the status of a single printer, either locally or on the network.  The
usual "lpq" or BSD "lpc" command will usually serve the purpose
adequately (Note for LPRng users, lpc has no "stat" function!).  In
this case, Monitor will replace the string HOST with a printer name.
For example, if you specify this with:

prnstat=/usr/local/bin/lpq -PHOST

then, when Monitor issues this command to, say "printer1", it will
become the command line:

/usr/local/bin/lpq -Pprinter1

This will generally only be useful to administrators who have network
printers in various locations that are open to several users.  For
networks with only local printers, this will probably go unused.

archive
	This is the absolute directory name of the location you'd like
to have archived copies of the output from Monitor go.  

copy
	This is the copy command for your system, with appropriate
flags to make sure the permissions are duplicated.  This is used when
copying the output of Monitor to the archive directory

wildcard
	This is the generic "all files" wildcard for your system.
Unix systems will typically use just "*".  This is provided so that
when Win95 support is added (which uses "*.*") there will be a minimal
amount of change needing to be done to the code.  This is used when
copying the entire contents of the output directory into the archive
directory.

null
	The null device on your system.  Unix will use /dev/null,
while Windows systems will traditionally use NUL.  Used for
compatibility, when a Windows version of Monitor becomes available.

pinglist, tracelist, printerlist, ruptimelist, ruptime2list
	These are the absolute paths to the files that contain the
hostnames/printer names to look at.  


CONFIGURATION SYNTAX:

	Now we come to the "syntax" stuff.  Syntax of the config files
is relatively easy.  The file monitor.loc must have at least 1 line,
consisting of the absolute path to the monitor.conf file.  This file
may contain comments, both before and after the actual location line,
which start with "#".  A typical monitor.loc file may read something
like:

# The location of the configuration file
# There can be as many comment lines as desired.
/usr/local/monitor/monitor.conf
# The line above is the only one that gets paid attention to

	Monitor only pays attention to the *first* uncommented line.
Any lines that are not commented *after* the first one are
disregarded.  Make sure the first one that doesn't begin with "#" has
the right location!
	The "monitor.conf" file has only a little more to it, as far
as syntax goes.  Lines starting with "#" are ignored as comment lines,
as typical.  The format of a valid line in this file is of the form:

parameter=value

where "parameter" is one of the items listed in "CONFIGURATION" above,
followed immediately by a "=" (no spaces permitted), and followed by
what you want that parameter to be set to.  While no spaces are
permitted between the parameter and the "=", spaces are permitted in
"value".  For example, if I want to use the default Linux "ping"
command to send a single packet to a host, and then exit, I would have
a line in monitor.conf reading:

ping=/bin/ping -c 1

The host to ping will be automatically appended to the end of the
command.  Note that the above line is equivalent to:

ping= /bin/ping -c 1

	In this case, the whitespace after the "=" is considered part
of the command line, and as such doesn't mean anything to the shell.

HOST FILES:

	There are a total of 5 host files in this release of monitor.
These are ping.hst, printers.hst, ruptime.hst, ruptime2.hst and
trace.hst.  The format of each file is identical, and each contains
the hostname or raw IP addresses of hosts to be watched.  Ping.hst
contains a list of hosts to regularly ping, printers.hst contains a
list of printer names that are to be watched (must have local printcap
entries), ruptime.hst and ruptime2.hst contain lists of machines to
keep track of the load and uptime on, and trace.hst has a list of
hosts to traceroute to.  The format is simply a single hostname per
line.
	The "include" statement is provided for additional
functionality.  Rather than maintaining up to 5 different lists of
hosts, each repeating the same contents, one may put an include
statement (or multiple include statements) into these files which
references a master list.  For example, if you want to keep watch over
5 TCP/IP networked printers, named "lp1" through "lp5", and 10 hosts,
named "host1" through "host10", you can set up a simple structure of
include statements that save you a lot of typing.  Each of the files
ping.hst, trace.hst, ruptime.hst and ruptime2.hst may include a single
file, in this case called "hosts.list", which contains the list of all
the relevant hosts.  This may be done with each of those 3 files
containing the single line:

include=/usr/local/monitor/hosts.list

	Ping and  traceroute can be performed on all the TCP/IP
printers, (assuming they appear in printers.hst) by simply adding the
line:

include=/usr/local/monitor/printers.hst

to ping.hst and trace.hst.  Additional, non-local machines can be
added to traceroute, for example, by specifying their names after the
include statements in trace.hst.  Thus, the contents of trace.hst
might look something like:

include=/usr/local/monitor/hosts.list
include=/usr/local/monitor/printers.hst
pop.fast.net
athos.rutgers.edu
www.math.brown.edu

	One note about include statements: a file which has been
included cannot contain include statements.  In the above example,
hosts.list and printers.hst cannot contain their own include
statements.  This is to avoid endless looping between two files which
include each other.  If an include statement exists where it shouldn't
be, it will be ignored.
	Note that the name ping.hst, trace.hst, etc. are just
suggestions.  They must be specified in monitor.conf explicitly, no
matter what you name them.

USAGE RECOMMENDATIONS:

	Why use monitor?  Well, it can help people like system
administrators and telecommunications people find where problems are,
and what time those problems occurred.  For example, in order to make
sure that my ISP is providing their service adequately, I have several
hosts just outside my ISP tracerouted and ping'd.  To make sure that
my ISP's ISP is doing their job correctly, I have several *very*
non-local hosts tracerouted and ping'd.  Depending on the output of
traceroute, I can tell who/where is possibly down.
	Also, it helps to find when gateways are not responding.  Here
at Rutgers, there are several Cisco boxes with at least half a dozen
(probably more) different net interfaces on them, but they are all
addressed with aliases to the same name.  For example,
rucs-gw.rutgers.edu is known as 128.6.40.1, 165.230.212.129,
128.6.63.1, 128.6.147.1, 165.230.208.2, and lots of other names.
Using the IP addresses of the individual interfaces, I can traceroute
and ping them, and thus determine if a particular interface is goofed
up, or if a certain router needs to be looked at.
	Use it to monitor any machine you wish.  It's always good to
know which machines and interfaces are up or down.  Also, this can help
people who are in a networked environment where re-wiring is taking
place or other possible network outages are common.

ABOUT THE SUPPLIED "ruptime" AND "ruptimed":

	Supplied with this package are two files, ruptime and
ruptimed.  Ruptimed is a server which reports back the hostname and
output from the "uptime" command (typically the amount of time the
system has been up, the number of users, and the load average).
Ruptimed runs on port 777.  If you find that port 777 is in use by
something else, please let me know (tkunz@triune.rutgers.edu)!  The
reason I am supplying these with this package are that many unices
(including Slackware Linux) do not come with a full suite of Sun RPC
(remote procedure call) stuff.  Quite a few don't come with an
"rpc.rstatd" or "rup".  So I wrote replacements for these, and have
made it so that if you have root access to a Linux machine that has no
rpc.rstatd or rup commands, you can install your own.  Install
ruptimed into your startup scripts with a "&" to background it, so
that it is present at boot time.  That way, if you have a
heterogeneous network with some machines that talk RPC, and some
machines that don't, just install ruptimed onto the ones that don't
and put in entries in monitor.conf as:

ruptime=/usr/local/bin/rup
ruptime2=/usr/local/bin/ruptime

	Then, (as long as you have RPC rup on the machine running
monitor) you will be able to see the uptime of your remote machines.

BUG REPORTS:

	Send any and all bug reports to:

	tkunz@triune.rutgers.edu

	If that address bounces, try me at:

	tkunz@fast.net

	If both those addresses bounce (and for my job's sake, I hope
they don't!!!), then you have a *really* outdated copy of this
document, and you should try looking for a newer copy.  If both those
addresses bounce and you find that this IS the newest version of this
document that you can find, then I am dead, and as such, have probably
ceased work on monitor.
	In a bug report, tell me where/how you obtained your copy of
monitor, the platform you are running it on, the version of Perl you
are using to invoke it, and as detailed of a description as you
possibly can about what happens.  Also, include with it a copy of the
log file that is generated when you issue "monitor once".  I may ask
you also for a copy of monitor.conf, should it come to that.

BUGS AND FEATURES:
	Here is a log of the bugs and desired features that have
become apparent in this version of Monitor (0.2alpha) and previous
versions (0.1alpha) in reverse order:

__________________________VERSION 0.2alpha____________________________

	1.) Lots of zombies abound *while* Monitor is executing.  I
suppose I should probably clean that up so that *no* zombies EVER
exist.  However, as this doesn't actually cause problems, I'm not
*too* inclined to fix it, unless there's some other real serious
problems caused by it.

	2.) It would be nice if you could include an "infinite" number
of levels of include files into your *.hst files.  Right now, an
included file can't include another, but it'd be good if you could,
and that Monitor would handle any "loop" conditions that may result. 

	3.) It'd be good to have it understand more than just the
parameter "once" on the command line.  It'd be good to make it so that
you can set debug levels, archival on/off, and override other
monitor.conf parameters.

__________________________VERSION 0.1alpha____________________________

	1.) The perl source of "monitor" *looks* like it can run itself,
fork and wait a period of time, then fork itself again and re-run on a
time-delayed basis.  Wrong.  I *tried* to make it fork and act kind of
like a daemon, but that has a few problems.  It will run, concurrently
fork out all the other "ping", "traceroute", etc. processes, but then
all those child processes end up as zombies.  Taken to it's logical
conclusion, after running itself several times, you will have a huge
number of processes marked as zombie and no processes left!  So
instead of fixing that right now, I decided to put in the "once"
command line parameter option.  So for now, the only intelligent way
to run Monitor is with the command line:

	monitor once

	It will run, fork off all the appropriate programs, generate
the HTML, and then exit.  If anyone out there wants to work on making
it fork and sleep (as is obviously desired) please do so and send me
the patches.  This could be a somewhat involved fix.

	2.) The file "monitor.loc" must ONLY be 1 line long, giving
the location of the config file, monitor.conf.  It'd be nice to have
it commentable.  Easy fix.

	3.) Files like monitor.conf that *can* have comment lines in
them will only regard a comment as such if the first character of the
line is a "#".  It'd be nice if it could be made so anything to the
right of any "#" is a comment.  Easy fix, but possibly more time than
I want to waste on it.

	4.) The *.hst files must be in the same directory as
"monitor".  This makes little sense right now, since monitor.conf can
reside anywhere on the machine, and everything else must be in the
same directory as "monitor".  It should be set up so that each file
can reside in a different location, and be specified in monitor.conf.

	5.) If a file is included from a .hst file, it will try to
interpret any additional include statements as host names.  It should,
in the best interest of not looping, simply ignore the additional
includes.  It's good that it won't try to include things a second
time, to avoid endless looping, but it should not try to interpret an
out-of-place "include" as a machine name.

