$Id: README.monitors,v 1.11 1999/08/16 00:25:05 trockij Exp $

The following monitors are provided with the distribution, to get
you started. It's simple to add your own monitors. See the man page
for "mon" to learn how.

fping.monitor
-------------
    This pings a list of hosts efficiently using the fping program,
    from the Satan distribution. fping.monitor is just a simple
    shell wrapper for fping, and is normally invoked with just the
    list of hosts to ping. Here's a trick: say you don't want to
    trigger an alert until a machine has unpingable for some number
    of minutes. Give fping.monitor the arguments "-r 3 -t 240000".

ping.monitor
------------
    Similar to fping.monitor, but uses the system's ping program.
    This serializes the pings, which is normally bad to do. This
    is simply an alternative to fping.monitor, if you can't get
    fping to compile. I've only tested it with Linux and Solaris.

freespace.monitor
-----------------
    This will monitor disk space usage of a particular NFS server.
    Arguments are supplied as "path:kBfree [path:kBfree...]". If
    free space dips below kBfree, then it returns a failure condition,
    and the output is how much space is left on that server.

    If you use this monitor, use separate mounts for the volumes that
    you want to test, mounting them with the "-o ro,intr,soft" options,
    so things don't hang too bad if the server is down.

    You should use the ";;" directive to the monitor line, because
    freespace.monitor doesn't take a list of hosts. Here's an example:

watch nfsservers
        service fping
            interval 5m
            monitor fping.monitor
            alert mail.alert mis-alert@company.com
            alert netpage.alert mis-pager
            alertevery 60m
        service freespace
            interval 10m
            monitor freespace.monitor /server1:5000000 /server2:5000000 ;;
            alert mail.alert mis-alert@company.com
            alert netpage.alert mis-pager
            alertevery 60m


tcp.monitor
-----------
    Useful to see if it's possible to connect to a particular port
    on a particular server. This is over-simplified, and does not yet
    support parsing of the output from these services. Options are
    "-p port" to tell which port to check, and a list of hosts.
    This uses Wietse Venema's tcp_scan software from the Satan package.


http_t.monitor
--------------
    This monitor, contributed by Jon Meek (meekj@pt.cyanamid.com), will
    use HTTP to connect to a server, get a page, and log the transfer
    speed of the transaction. It uses the Time::HiRes Perl module,
    available from CPAN. It can also register a failure if the transfer
    doesn't complete within a certain number of seconds. See the
    source code for an explanation of the arguments.

dns.monitor
-----------
    dns.monitor will make several DNS queries to verify that a server is
    providing the correct information for a zone. The zone argument is
    the zone to check. There can be multiple zone arguments. The master
    argument is the master server for the zone.  It will be queried for
    the base information.  Then each server will be queried to verify
    that it has the correct answers.  It is assumed that each server is
    supposed to be authoritative for the zone.

ftp.monitor
-----------
    Connect to an ftp server, wait for an acceptible prompt, and log
    out.

hpnp.monitor
------------
    Uses SNMP to monitor HP JetDirect-equipped printers. Reports
    failures as told by the various objects in HP's MIB, and returns
    the message that is showing on the printer's LCD ("LOW TONER",
    "LOAD LETTER", etc.).

http.monitor
------------
    Connects to an http server, retrieves a URL, and returns true
    if everything is OK.

imap.monitor
------------
    Connects to an IMAP server, checks for a sane response, and
    then logs out.

ldap.monitor
------------
    This script will search an LDAP server for objects that match the
    -filter option, starting at the DN given by the -basedn option. Each
    DN found must contain the attribute given by the -attribute option
    and the attribute's value must match the value given by the -value
    option.  Servers are given on the command line. At least one server
    must be specified.

netappfree.monitor
------------------
    Use SNMP to get free disk space from a Network Appliance
    exits with value of 1 if free space on any host drops below
    the supplied parameter, or exits with the value of 2 if
    there is a "soft" error (SNMP library error, or could not get a
    response from the server).

    This requires the UCD SNMP library and G.S. Marzot's Perl SNMP
    module.

    Supply a configuration file with "--config file" option (see
    etc/netappfree.cf for an example), or "--list" for a listing
    of filesystems which are on your filers. Use --list for help in
    building a configuration file.

nntp.monitor
------------
    Tries to connect to a nntp server, and wait for the right output.

ping.monitor
------------
    Returns a list of hosts which not reachable via ICMP echo. Uses the
    system's default ping, rather than fping.

pop3.monitor
------------
    Connects to a POP3 server, waits for the OK prompt, then logs out.

process.monitor
---------------
    Monitor snmp processes.

    Arguments are:  [-c community] host [host ...]

    This script will exit with value 1 if host:community has
    processErrorFlag set.  The summary output line will be the host names
    that failed and the name of the process.  The detail lines are what
    UCD snmp returns for an ErrorMsg.  ('Too (many|few) (name) running (#
    = x)').  If there is an SNMP error (either a problem with the SNMP
    libraries, or a problem communicating via SNMP with the destination
    host), this script will exit with a warning value of 2.

    There probably should be a better way to specify a given process to
    watch instead of everything-ucd-snmp-is-watching.

reboot.monitor
--------------
    Polls the SNMP agent on hosts, and triggers a failure when a reboot
    is detected.

smtp.monitor
------------
    Connects to an SMTP server, waits for a prompt, and then logs out.

telnet.monitor
--------------
    Use tcp_scan to try to connect to the telnet port on a bunch of hosts,
    and look for a "login" prompt.

msql-mysql.monitor, rpc.monitor
-------------------------------
    See the separate README for these monitors.

readdir.monitor
---------------
    From: gilles LamiraL <lamiral@mail.dotcom.fr>
    To: "mon@linux.kernel.org" <mon@linux.kernel.org>
    Subject: readdir monitor

    Hello,

    I wrote a monitor that reads several directories and tells
    if the number of files in each directory exceeds a given number.
    Possible uses are testing /var/spool/mqueue or /var/spool/lp/
    It is a local monitor. No SNMP here. I think it can be easyly
    called from an SNMP agent.

    1) The allowed number can be specified for each directory.

    2) You can add a regex filter to match the file names.
       Only one regex is allowed for all directories.
       Tell me if you want one for directory.

    3) The return status is interesting. It gives the exceeded values 
       in a log based 2 way.

    For example: 
    You want to check if /var/spool/mqueue contains less than 100 messages

    $ ls /var/spool/mqueue | wc -l
    479
    $ ./my-readdir.monitor /var/spool/mqueue:100
    /var/spool/mqueue:479
    $ echo $?
    3

      1 means more than 100 messages
      2 means more than 200 messages
      3 means more than 400 messages
      4 means more than 800 messages

    ...
    255 means more than 5.79 * 10^76 messages (579 + 74 zeros !)
       
    Nice ?
    See more example in the script itself.


up_rtt.monitor
--------------
    mon monitor to check for circuit up and measure RTT. Jon Meek - 09-May-1998.
    Requires Perl Modules "Time::HiRes" and "Statistics::Descriptive".


dialin.monitor
--------------
    Dials in to a modem and fails if a carrier and a prompt is not
    detected.  Useful for telling if your modem pool is down or if some
    spaz modem has quit answering the phone.

    dialin.monitor requires the Perl Expect module, available from
    CPAN.

    This program performs UUCP-style locking, and needs to run setgid
    uucp to accomplish this. Provided is dialin.monitor.wrap.c, a simple
    little C program which is installed as setgid uucp and directly
    executes the actual dialin.monitor Perl script. This is required
    because some systems (e.g. Linux) do not allow setuid/setgid scripts.

    To build, edit the Makefile in mon.d, and adjust monpath to your
    environment. The do:

    make && make install

    dialin.monitor accepts several arguments. The only required argument
    is "-n", which specifies the phone number to dial.

    -n number	dial in to "number"
    -t secs	timeout to wait for "CONNECT" from modem (60)
    -l lockdir	directory to use for UUCP-style locking ("/var/lock")
    -D device	serial device to use ("/dev/modem")