You are on page 1of 4

6/14/2016

EventHandlers

EventHandlers
UpTo:Contents
SeeAlso:StateTypes,HostChecks,ServiceChecks

Introduction
Eventhandlersareoptionalsystemcommands(scriptsorexecutables)thatarerunwheneverahostorservice
statechangeoccurs.
AnobvioususeforeventhandlersistheabilityforNagiostoproactivelyfixproblemsbeforeanyoneisnotified.
Someotherusesforeventhandlersinclude:
Restartingafailedservice
Enteringatroubleticketintoahelpdesksystem
Loggingeventinformationtoadatabase
Cyclingpoweronahost*
etc.
*Cyclingpoweronahostthatisexperiencingproblemswithanauomatedscriptshouldnotbeimplementedlightly.Considerthe
consequencesofthiscarefullybeforeimplementingautomaticreboots.:)
WhenAreEventHandlersExecuted?
Eventhandlersareexecutedwhenaserviceorhost:
IsinaSOFTproblemstate
InitiallygoesintoaHARDproblemstate
InitiallyrecoversfromaSOFTorHARDproblemstate
SOFTandHARDstatesaredescribedindetailhere.
EventHandlerTypes
Therearedifferenttypesofoptionaleventhandlersthatyoucandefinetohandlehostandstatechanges:
Globalhosteventhandler
Globalserviceeventhandler
Hostspecificeventhandlers
Servicespecificeventhandlers
Globalhostandserviceeventhandlersarerunforeveryhostorservicestatechangethatoccurs,immediatelypriortoanyhostor
servicespecificeventhandlerthatmayberun.Youcanspecifyglobaleventhandlercommandsbyusing
theglobal_host_event_handlerandglobal_service_event_handleroptionsinyourmainconfigurationfile.
https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/3/en/eventhandlers.html

1/4

6/14/2016

EventHandlers

Individualhostsandservicescanhavetheirowneventhandlercommandthatshouldberuntohandlestatechanges.Youcanspecify
aneventhandlerthatshouldberunbyusingtheevent_handlerdirectiveinyourhostandservicedefinitions.Thesehostandservice
specificeventhandlersareexecutedimmediatelyafterthe(optional)globalhostorserviceeventhandlerisexecuted.
EnablingEventHandlers
Eventhandlerscanbeenabledordisabledonaprogramwidebasisbyusingtheenable_event_handlersinyourmainconfiguration
file.
Hostandservicespecificeventhandlerscanbeenabledordisabledbyusingtheevent_handler_enableddirectivein
yourhostandservicedefinitions.Hostandservicespecificeventhandlerswillnotbeexecutedifthe
globalenable_event_handlersoptionisdisabled.
EventHandlerExecutionOrder
Asalreadymentioned,globalhostandserviceeventhandlersareexecutedimmediatelybeforehostorservicespecificevent
handlers.
EventhandlersareexecutedforHARDproblemandrecoverystatesimmediatelyafternotificationsaresentout.
WritingEventHandlerCommands
Eventhandlercommandswilllikelybeshellorperlscripts,buttheycanbeanytypeofexecutablethatcanrunfromacommand
prompt.Ataminimum,thescriptsshouldtakethefollowingmacrosasarguments:
ForServices:$SERVICESTATE$,$SERVICESTATETYPE$,$SERVICEATTEMPT$
ForHosts:$HOSTSTATE$,$HOSTSTATETYPE$,$HOSTATTEMPT$
Thescriptsshouldexaminethevaluesoftheargumentspassedtoitandtakeanynecessaryactionbaseduponthosevalues.Thebest
waytounderstandhoweventhandlersworkistoseeanexample.Luckyforyou,oneisprovidedbelow.
Tip:Additionalsampleeventhandlerscriptscanbefoundinthecontrib/eventhandlers/subdirectoryoftheNagiosdistribution.
Someofthesesamplescriptsdemonstratetheuseofexternalcommandstoimplementaredundantanddistributedmonitoring
environments.
PermissionsForEventHandlerCommands
EventhandlercommandswillnormallyexecutewiththesamepermissionsastheuserunderwhichNagiosisrunningonyour
machine.Thiscanpresentaproblemifyouwanttowriteaneventhandlerthatrestartssystemservices,asrootprivilegesaregenerally
requiredtodothesesortsoftasks.
IdeallyyoushouldevaluatethetypesofeventhandlersyouwillbeimplementingandgrantjustenoughpermissionstotheNagiosuser
forexecutingthenecessarysystemcommands.Youmightwanttotryusingsudotoaccomplishthis.
ServiceEventHandlerExample
TheexamplebelowassumesthatyouaremonitoringtheHTTPserveronthelocalmachineandhavespecifiedrestarthttpdasthe
eventhandlercommandfortheHTTPservicedefinition.Also,Iwillbeassumingthatyouhavesetthemax_check_attemptsoptionfor
theservicetobeavalueof4orgreater(i.e.theserviceischecked4timesbeforeitisconsideredtohavearealproblem).An
abbreviatedexampleservicedefinitionmightlooklikethis...

defineservice{

host_name

service_description

max_check_attempts

event_handler

...

somehost
HTTP

4
restarthttpd

Oncetheservicehasbeendefinedwithaneventhandler,wemustdefinethateventhandlerasacommand.Anexamplecommand
definitionforrestarthttpdisshownbelow.NoticethemacrosinthecommandlinethatIampassingtotheeventhandlerscriptthese
areimportant!
https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/3/en/eventhandlers.html

2/4

6/14/2016

definecommand{

command_name

command_line

EventHandlers

restarthttpd
/usr/local/nagios/libexec/eventhandlers/restarthttpd$SERVICESTATE$$SERVICESTATET

Now,let'sactuallywritetheeventhandlerscript(thisisthe/usr/local/nagios/libexec/eventhandlers/restarthttpdscript).

#!/bin/sh
#
#Eventhandlerscriptforrestartingthewebserveronthelocalmachine
#
#Note:Thisscriptwillonlyrestartthewebserveriftheserviceis
#retried3times(ina"soft"state)orifthewebservicesomehow
#managestofallintoa"hard"errorstate.
#

#WhatstateistheHTTPservicein?
case"$1"in
OK)

#Theservicejustcamebackup,sodon'tdoanything...

;;
WARNING)

#Wedon'treallycareaboutwarningstates,sincetheserviceisprobablystillrunning...

;;
UNKNOWN)

#Wedon'tknowwhatmightbecausinganunknownerror,sodon'tdoanything...

;;
CRITICAL)

#Aha!TheHTTPserviceappearstohaveaproblemperhapsweshouldrestarttheserver...

#Isthisa"soft"ora"hard"state?

case"$2"in

#We'reina"soft"state,meaningthatNagiosisinthemiddleofretryingthe

#checkbeforeitturnsintoa"hard"stateandcontactsgetnotified...

SOFT)

#Whatcheckattemptareweon?Wedon'twanttorestartthewebserveronthefirst

#check,becauseitmayjustbeafluke!

case"$3"in

#Waituntilthecheckhasbeentried3timesbeforerestartingthewebserver.

#Ifthecheckfailsonthe4thtime(afterwerestartthewebserver),thestate

#typewillturnto"hard"andcontactswillbenotifiedoftheproblem.

#Hopefullythiswillrestartthewebserversuccessfully,sothe4thcheckwill

#resultina"soft"recovery.Ifthathappensnoonegetsnotifiedbecausewe

#fixedtheproblem!

3)

echon"RestartingHTTPservice(3rdsoftcriticalstate)..."

#CalltheinitscripttorestarttheHTTPDserver

/etc/rc.d/init.d/httpdrestart

;;
https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/3/en/eventhandlers.html

3/4

6/14/2016

EventHandlers

esac
exit0

;;

esac

#TheHTTPservicesomehowmanagedtoturnintoaharderrorwithoutgettingfixed.
#Itshouldhavebeenrestartedbythecodeabove,butforsomereasonitdidn't.
#Let'sgiveitonelasttry,shallwe?
#Note:Contactshavealreadybeennotifiedofaproblemwiththeserviceatthis
#point(unlessyoudisablednotificationsforthisservice)
HARD)

echon"RestartingHTTPservice..."

#CalltheinitscripttorestarttheHTTPDserver

/etc/rc.d/init.d/httpdrestart

;;
esac
;;

Thesamplescriptprovidedabovewillattempttorestartthewebserveronthelocalmachineintwodifferentinstances:
Aftertheservicehasbeenrecheckedforthe3rdtimeandisinaSOFTCRITICALstate
AftertheservicefirstgoesintoaHARDCRITICALstate
ThescriptshouldtheoreticallyrestartandwebserverandfixtheproblembeforetheservicegoesintoaHARDproblemstate,butwe
includeafallbackcaseintheeventitdoesn'tworkthefirsttime.Itshouldbenotedthattheeventhandlerwillonlybeexecutedthefirst
timethattheservicefallsintoaHARDproblemstate.ThispreventsNagiosfromcontinuouslyexecutingthescripttorestarttheweb
serveriftheserviceremainsinaHARDproblemstate.Youdon'twantthat.:)
That'sallthereistoit!Eventhandlersareprettysimpletowriteandimplement,sogiveitatryandseewhatyoucando.

https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/3/en/eventhandlers.html

4/4