Guard event monitoring reference

Overview

MagiKmon Guard expect to receive status updates from outside at regular interval. If no update append during a defined period, the status switch to failed. Update can come from emails or HTTP requests.

Mail driven update

Some appliance, like NAS, can send an email status at regular interval to a MagiKmon service. MagiKmon can read the email, search for some character patterns in the subject or the body and update the status accordingly. If no email is received for too long then the service will switch to failed state and raise the appropriate alerts.

For now only Custom configuration are allowed. The user has to know the format of the email and configure himself the pattern to search and the related action. Pre-configured setup will come with user's requests.

The email address of the service is available on the configuration screen of the service.

HTTP driven event

This service is based on the HTTP protocol. A simple HTTP request updates the service status. Scripts can use this feature to add monitoring to a lot of applications. Some trivial but useful samples are explained later.

An additional status parameter can be attached to the request to set the status to the value you want. The only recognized value is OK in upper case. ERR can be used to report an error, but any other value will be understood as an error too ! Be careful !
If no requests are received in the defined period, the service will switch to the failed state. Any monitor attached to this service will raise an alert as soon as the grace period has expired.

A dedicated VMware Esx(i) class can be used to receive update from the esxmon module of MKSBackup. This module collect and report problem about the hardware of your VMware ESX(i) server.

The URL you have to use is available on the configuration screen of the service.

Common configuration parameters

Description

This is the name of the service.

Frequency

This is the minimum rate at witch the service expect to be updated. When no event has been received during this period, the status switch to error. Try to update the service at twice this rate, that way if one update cannot be recorded by MagiKmon for any reason, you have a second chance before the service switches to error. MagiKmon use a margin of 20% to handle small time shift or delayed mail delivery. Of course, the service will switch to error immediately when it receive an error event.

Don't confuse this value with the grace period used in monitors ! After the service has switched to error, the monitor will wait for this grace period before to raise an alert. If the service switch back to OK in between, the monitor is disarmed.

If you are monitoring a VMware Esx(i), select a frequency of at least 1H because MKSBackup update the status every 55min maximum !

For example if your NAS send an email every hour and you have set the frequency to two hours and attached a monitor with a grace period of one hour and if last email was received a 12H00, the service will switch to error at 14H24 (2H+20%) and raise an alert 1 hour later at 15H24. If an email is received before 14H24 nothing will append and MagiKmon will wait 2H24 after the email receipt before to switch to error again. If the email is received between 14H24 and 15H24, the service will switch to error, (and this will be visible on the service time line) but the monitor will not raise any alert.

Configuration parameters related to Email Guard

Class

Only Custom class is available for now. It allows any user to set the character pattern the agent will have to search in received emails.

Sender

This is the expected sender address. If this field don't match the email sender then the email is ignored. This is to be sure email is coming from monitored target and has not been forged by an evil pirate. This field can be left empty.

Rules

Rules are handled in the order of definition, the first to match the email decide the action.
What select witch part of the email will be used:

• Subject: The email subject.
• Body: The email body.
• Header: can be used to search for a header value.

Pattern for Header is in two part, for example :

Virus-Status:OK

Will search for the characters OK in the Virus-Status header field if it exist in the email.

Action define the action if the pattern match.

• Ignore: the email is ignored and status is nod modified.
• Success: the status is set to OK.
• Failure: status is switched to failed state.

Configuration parameters related to HTTP interface

Class

This is Basic for a basic one, or VMware Esx(i) to monitor a VMware server.

Secret

This string is used to guarantee the request is coming from you and not forged by an evil program or pirate.

Usage samples

Except for MKSBackup that has built-in support, you need to use a tools to make your HTTP request. You can use you web browser for testing purpose ! The recommended tool is wget ! Already installed on most Linux system, it is easy to find as wget.exe for Windows platform.

To make a simple request use it like that, 123 is the Id if the service:

  wget --quiet "http://monitoring.magikmon.com/guard/123/mysecret"
  

To report an error use it like that:

  wget --quiet "http://monitoring.magikmon.com/guard/123/mysecret?status=ERR"
  

A success can be forced that way even if the result is identical to the first one:

  wget --quiet "http://monitoring.magikmon.com/guard/123/mysecret?status=OK"
  

Another way to use wget with more debugging and using a POST request :

  wget --quiet --save-headers -O - --post-data "status=OK" "http://monitoring.magikmon.com/guard/123/mysecret"
  

You can combine the use of wget with any other application in a simple script, here are some samples.

Simple heartbeat usage

Put the wget command in your Windows task scheduler or in your Linux crontab to get the simplest possible monitoring !
When the status switch to error you know something is going wrong at your office ! A server failure, a power cut or an Internet failure ? Monitoring multiple hosts could help to make a more precise diagnostic.

Status of XCOPY under Windows

Use Windows XCOPY to copy your My Documents folder to your backup drive F:. When done report the appropriate status using wget.exe

  xcopy "c:\Documents and Settings\username\My Documents" F:\backup /s /e
  IF ERRORLEVEL 1 goto ERROR
  wget.exe --quiet http://monitoring.magikmon.com/guard/123/mysecret?status=OK
  goto END
  :ERROR
  wget.exe --quiet http://monitoring.magikmon.com/guard/123/mysecret?status=ERR
  :END
  

Status of tar command under Linux

Under Linux archive your HOME directory and upload it using FTP, then report the final status using wget !

  filename=$(mktemp -p /tmp myhomeXXXX.tgz)
  tar czf $filename /home/username && curl -T $filename ftp://username:password@yourserver/bacupdir
  if [ "$?" == "0" ] ; then
      wget --quiet http://monitoring.magikmon.com/guard/123/mysecret?status=OK
  else
      wget --quiet http://monitoring.magikmon.com/guard/123/mysecret?status=ERR
  fi
  rm $filename