addons:messaging.sh

Differences

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

Link to this comparison view

addons:messaging.sh [2009/12/17 11:26] (current)
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
  • (external edit)