====== 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: [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 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 #!/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 ${msgfile} `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} Details: Contents of ${MESSAGEDIR} on ${MACHINE} ${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. ===== Known Bugs and Issues ===== ===== To Do ===== ===== Credits ===== ===== Changelog ===== * **2009-12-16** * Initial release