addons:messaging.sh

no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.


—addons:messaging.sh [2009/12/17 11:26] (current) – created - external edit 127.0.0.1
Line 1: Line 1:
 +====== messaging.sh ======
 +
 +^ Author | [[ stuart@carmichael.net.au | Stuart Carmichael ]] |
 +^ Compatibility | Xymon 4.2 |
 +^ Requirements | linux/unix |
 +^ Download | See Source, below |
 +^ Last Update | 2009-12-16 |
 +
 +===== Description =====
 +I want a way to message the sysadmin of my server. The message might be a
 +status message from a backup (success/fail), or any sort of automated job.
 +It could be a reminder to myself ("don't forget to bring home bread").
 + 
 +The way I have implemented this is as separate text files in a messaging
 +directory. When an automated job/application/user creates a text file in
 +the $MESSAGEDIR, Xymon will display the status under the "messaging"
 +column. There may be any number of messages in the messaging directory
 +(the highest priority message will be the status of the entire group for
 +this host). A keyword 'red', 'yellow' or 'green' determines the priority
 +of the message.
 +
 +This script continually monitors the $MESSAGEDIR, and will remove message
 +details from Xymon once the message files themselves have been dealt with
 +(for example: automatically via a cron job; manually deleted/edited once
 +the issue has been dealt with).
 +
 +If no messages appear in $MESSAGEDIR, the status for this host is "clear".
 +
 +{{:addons:messaging.jpg|}}
 +
 +===== Installation =====
 +This is a client side script. The following must be completed on all Xymon client which you
 +
 +want to send messages to the server.
 +
 +1. Copy the script (see below, Source Code) 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:
 +
 +<code>
 +[messaging]
 +        ENVFILE $HOBBITCLIENTHOME/etc/hobbitclient.cfg
 +        CMD $HOBBITCLIENTHOME/ext/messaging.sh
 +        LOGFILE $HOBBITCLIENTHOME/logs/messaging.log
 +        INTERVAL 5m
 +</code>
 +
 +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
 +
 +
 +Script will create “messaging” alerts of the appropriate severity level when text files are created in the $MESSAGEDIR directory. The first word on the first line of each text message file defines the severity level. Severity levels can be one of: green, yellow, red. Any other severity level is assumed to mean 'red'. The remaining text in the messaging file is displayted as additional information in the messaging window.
 +
 +===== Source =====
 +==== messaging.sh ====
 +
 +Download and save the attached code into your client's ext directory. Save the file as messaging.sh
 +
 +<hidden onHidden="Show Code ⇲" onVisible="Hide Code ⇱">
 +<code>
 +#!/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.
 +</code>
 +</hidden>
 +
 +===== Known  Bugs and Issues =====
 +
 +===== To Do =====
 +
 +===== Credits =====
 +
 +===== Changelog =====
 +
 +  * **2009-12-16**
 +    * Initial release
  
  • addons/messaging.sh.txt
  • Last modified: 2009/12/17 11:26
  • by 127.0.0.1