svcmon - Versatile TCP Service Monitor
Introduction
svcmon is a versatile TCP service watchdog, that can optionally send email alerts when services are detected as being down.
svcmon is written using Perl, and requires a few "standard" Perl modules, which should be included as part of your base Perl installation:
Net::SMTP IO::Socket Getopt::Std
Head to the bottom of this page for the download...
Installation
Download the tarball, and extract to an appropriate location, e.g.:
# cd /usr/local
# wget http://www.zazzybob.com/svcmon/svcmon.tar.gz
# tar xzf ./svcmon.tar.gz
# ls ./svcmon
README bin etc
There are TWO configuration files (discussed below):
# cd /usr/local/svcmon
# ls etc
svcmail.conf svcmon.conf
Ensure that svcmon.pl is executable before continuing:
# chmod u+x /usr/local/svcmon/bin/svcmon.pl
Configuration
svcmon is configured via two configuration files:
$SVCMON_HOME/etc/svcmail.conf - Configure variables for email alerting $SVCMON_HOME/etc/svcmon.conf - Configure services that will be monitored
In order to ensure that the svcmon.pl script knows where to find these configuration files, modify the $config_file and $mail_config variables in $SVCMON_HOME/bin/svcmon.pl. As shipped, the default configuration is:
# egrep -n '^our.*\$(config_file|mail_config).*$' svcmon.pl
23:our $config_file = "/usr/local/svcmon/etc/svcmon.conf";
24:our $mail_config = "/usr/local/svcmon/etc/svcmail.conf";
If installed as described, there'll be no need to modify these.
First, we'll discuss the svcmail.conf file.
svcmail.conf
This file contains definitions of four variables. This file MUST exist, and all variables MUST be defined. If you're not planning on using the mail functionality, set SMTP_GATEWAY as follows:
SMTP_GATEWAY = null
and define bogus values for the other variables.
Let's take a look at a sample svcmail.conf file:
# svcmon.pl Mail Configuration MAIL_FROM = kevin@zazzybob.com MAIL_TO = kevin@localhost SMTP_GATEWAY = 192.168.0.1 HELO = localhost
The file is very self explanatory. MAIL_FROM defines who the email alerts should be addressed from. MAIL_TO specifies the recipient of the email alert. SMTP_GATEWAY is the IP address or hostname of your SMTP gateway, and HELO is the HELO string to send to the SMTP server when initiating the SMTP connection.
The main configuration is defined in svcmon.conf, so we'll discuss that next.
svcmon.conf
This file is best explained via an example. So here is the default svcmon.conf file, as shipped:
# svcmon configuration file # no inline comments allowed # ONLY TCP protocol supported at this point # svcid:Description:ip_addr:port:protocol:action # Allowed actions: # i - Ignore - do nothing # m - Mail - send mail httpd:HTTP Service (localhost):127.0.0.1:80:tcp:m sshd:SSH Service (localhost):127.0.0.1:22:tcp:i named:BIND (TCP) (localhost):127.0.0.1:53:tcp:i
Again, fairly self-explanatory, but I'll cover the main points below.
The file consists of six colon-delimited fields. If there aren't six fields, that line in the configuration file will be ignored (and a warning will be displayed, although svcmon will still process all other entries).
WHOLE-LINE comments, and blank lines are allowed within the file.
The first field contains a service ID, which does not need to be unique.
The second field contains a descriptive text description of the service being monitored, and can obviously not contain the : character ;-)
The third field is the IP address on which the monitored service listens. As shipped, the configuration lists localhost-only addresses, but obviously any legal IP address can be specified. PLEASE only use this for testing services on your OWN systems. svcmon could be put to use as an effective (albiet slow) port scanner, but this is NOT why it has been designed!
The forth field is the port number on which the monitored service listens.
The fifth field is the protocol over which the service communicates. HOWEVER, please not that the TCP protocol is the ONLY supported protocol at present.
The sixth field contains the action to perform when a service is detected as being down. "i" indicates that the alert should be ignored. You will see that the service is down when svcmon.pl is used interactively. An "m" in this field indicates that an email alert of the services DOWN status should be sent to the MAIL_TO address specified in your svcmail.conf file.
That is pretty much all there is to it. svcmon.pl is very simple to configure, but is a highly powerful utility.
Putting It All Together
Once your svcmon configuration is complete, try running the command interactively to ensure that all is well:
# /usr/local/svcmon/bin/svcmon.pl
------------------------------------------------------------
Service Status:
------------------------------------------------------------
DOWN: HTTP Service (localhost) (httpd) on 127.0.0.1:80[tcp]
UP: SSH Service (localhost) (sshd) on 127.0.0.1:22[tcp]
UP: BIND (TCP) (localhost) (named) on 127.0.0.1:53[tcp]
If you've configured mail correctly you should receive a message notifying you for each service that is DOWN.
If you want to use the script as it's intended, as an unattended service monitor with email alerting, add an entry as follows to your root crontab
0,10,20,30,40,50 * * * * /usr/local/svcmon/bin/svcmon.pl >/dev/null 2>&1
Obviously, the frequency of service-checking is totally down to you.
You could even chose to run the script piping the output to mail (and setting you service definitions to "[i]gnore" in svcmon.conf) to receive a regular digest of service availability, although I'd rather just get a "[m]ail" when a service is DOWN.
You can also run svcmon.pl in -v (verbose) and -d (debug) mode. Type
# /usr/local/svcmon/bin/svcmon.pl -h
For full details.
Download
You can grab the latest svcmon tarball here.
Comments, suggestions, etc. are always welcome (email address below).
Cheers
Kevin Waldron
kevin@zazzybob.com
