messaging.sh

#!/bin/sh
# messaging.sh - script to look for status messages posted into
# $MESSAGEDIR and report to Xymon.
#
# See comments at end of file for installation instructions
#
# Messages posted into $MESSAGEDIR are simple text files in the form of:
# Filename - name of test/class
# Contents of file:
# Field 1: Keyword RED YELLOW GREEN indicating severity
# Remainder of line 1: Status message to display
# Based on example script at http://www.xymon.com/hobbit/help/hobbit-tips.html#scripts
# Restrictions:
#  1. message filename cannot contain spaces
#  2. First word of the message file must be 'red' 'yellow' or 'green' (case insensitive)
#     If this condition is not met, 'red' is assumed
#  3. The 'xymon' user MUST have read access to $MESSAGEDIR
#  4. If $MESSAGEDIR does not exist, this script attempts to create it. The 'xymon' user
#     MUST have write access to the directory above $MESSAGEDIR in this case, or the directory
#     should be created manually prior to implementing this script
# 
# Author: Stuart Carmichael stuart at carmichael dot net dot au
# Date: 16/12/09 v0.1 Initial version
# Modifications:
#

MESSAGEDIR=/usr/local/xymon/messages
COLUMN=messaging	# Name of the column
STAT_COLOR=clear		# Overall status; By default, everything is OK. start with clear: assume no message files to be processed
export MSG=""
export LINE="" 		# string containing final status sent to server



# Create the $MESSAGEDIR if it does not exist
if [ ! -d $MESSAGEDIR ]; then 
  mkdir -p $MESSAGEDIR
fi

# Look for regular files in $MESSAGEDIR and process:

for msgfile in `ls $MESSAGEDIR`; do
  if [ "${STAT_COLOR}" = "clear" ]; then 
    STAT_COLOR=green # If I made it here, there must be message files. default colour is green
  fi

  if [ -f "${MESSAGEDIR}/${msgfile}" ]; then # file is a regular file

    COLOR="`head -1 ${MESSAGEDIR}/${msgfile}|awk '{ print $1 }'|sed 's/://g'`" #1st element; 1st line

# convert $COLOR to lowercase for consistency:
    COLOR="`echo $COLOR|tr [A-Z] [a-z]`"

    case $COLOR in
      green)
        linestat="OK"
        ;;
      yellow)
        linestat="Warning"
        ;;
      *)
        COLOR="red"
        linestat="Alert"
        ;;
    esac
 
# calculate the final STAT_COLOR:
#     if [ "$STAT_COLOR" = "red" ]; then
#       continue  # do nothing; we're already in alert
#     fi

    if [ "$STAT_COLOR" = "yellow" ]; then
      if [ "$COLOR" = "red" ]; then
        STAT_COLOR="red"    # promote from warn to alert
      fi
    fi

    if [ "$STAT_COLOR" = "green" ]; then
      if [ "$COLOR" = "red" ]; then
        STAT_COLOR="red"    # promote from OK to alert
      fi
      if [ "$COLOR" = "yellow" ]; then
        STAT_COLOR="yellow"    # promote from OK to warn
      fi
    fi
# otherwise the STAT_COLOR stays green

# now form the status display:
# The status display is 2 parts:
# 1. A summary of all the message files found, including red/gree/yellow
#    and a brief status message (the $LINE variable)
# 2. detailed output containing the text of all the message files found
#    (the $MSG variable)
    LINE="$LINE
&${COLOR} ${msgfile} Status ${linestat} "

    MSG="$MSG
<Font Size=+1><b>${msgfile}</b></Font>
`cat ${MESSAGEDIR}/${msgfile}` 
"

  fi  # end if [ -f ${messagefile} ]

done 
# Putting it all together:
LINE="status ${MACHINE}.${COLUMN} ${STAT_COLOR} `date`
${LINE}

"
if [ "${STAT_COLOR}" = "clear" ]; then  
  LINE="${LINE}

No messaging to report"
else
  LINE="${LINE}

<Font Size=+2><b> Details: </b></Font>
<Font Size=-1> Contents of ${MESSAGEDIR} on ${MACHINE} </Font Size>
${MSG}
"
fi
# Tell Xymon about it

# Debugging: uncomment the following line & comment out the $BB line to run interactively
# echo $LINE
$BB $BBDISP "$LINE"

exit 0

# ========================================================
# Installation Instructions
# 
This is a client side script. The following must be completed on amm Xymon client which you 
want to send messages to the server.
1. Copy this scriot into the Client's ext directory (ensure script is executable by the xymon user)
2. Update the client's etc/clientlaunch.cfg to include  the following:
[messaging]
	ENVFILE $HOBBITCLIENTHOME/etc/hobbitclient.cfg
	CMD $HOBBITCLIENTHOME/ext/messaging.sh
	LOGFILE $HOBBITCLIENTHOME/logs/messaging.log
	INTERVAL 5m
3. (optional) review the messaging.sh script, and change the location of $MESSAGEDIR to somewhere more 
   appropriate to your server (default is /usr/local/xymon/messages
4. Create the $MESSAGEDIR directory. Ensure the xymon user can read files in this directory

How it works:
Any text file created in $MESSAGEDIR is read by the script and becomes a 'message' on the server.
The first word of the first line determines the status/severity of the message. Valid keywords are 
'red' (alert), 'yellow' (warning) or 'green' (OK). Any keyword other than these 3 is assumed to be 'red'.
Status keywords are case-insensitive.

Once this script has detected a message file in $MESSAGEDIR, the xymon server is alerted with the appropriate
severity. The text included in the mesage file is displayed in the detail section of the alert.

No files in the $MESSAGEDIR sets the server status to 'clear'.

Alerts are cleared from the server once the message files have been delt with. This might be a manual operation 
of changing the status within the file to 'green' (or deleting the message file); or it could be an automated 
apprach (eg a cron job removing all files in $MESSAGEDIR at midnight.

Typical application:
Nightly backup completes. The script controlling the backup writes the final exit status of the backup
to $MESSAGEDIR/backup_status. The first keyword of this file indicates the exit status of backup (red, yellow, green).
Optionally text can follow this which might give additional information (320GB backed up in 42 minutes. completed at 02:45AM)

Once the above file is readable by the xymon client user, the details are sent to the server, and the appropriate status
is set against this client.

If the status is red, the messaging status will flash red until the condition is rectified.