Icinga

7.17. Recurring Downtimes

7.17.1. Downtime definition
7.17.2. Variable dates
7.17.3. Local holidays
7.17.4. Entering downtimes
7.17.5. Planning downtimes
7.17.6. Converting downtime definitions
7.17.7. Files

Many people have regular downtimes at different times and it would be a tedious task to reschedule them manually every time. So far there is no official format for defining such schedules. That means that these definitions have to be stored in a separate file which cannot be included into the other object definitions. A cronjob will call a script which will read the definitions, already existing downtimes, and plan new downtimes if necessary.

7.17.1. Downtime definition

The script introduces a new format for these downtimes based on existing definitions taken from the status file and time periods resulting in:

 define downtime {
    host_name           some host 
    hostgroups          some hostgroup
    servicegroups       some servicegroup
    service_description some service
    author              some author
    comment             some comment
    duration            30
    downtime_period     2011-10-02 - 2011-10-10 10:00-12:00
    fixed               0
    propagate           1
    register            0
}

Notes on the above definition:

7.17.2. Variable dates

The definitions above will work for most dates but some are calculated based on easter sunday which is on a different date each year. We tried to bypass these limitations by calculating the dates based on easter sunday and giving them names you can refer to. The variable names are not case sensitive.

Variable name Offset / Date
Twelfth_day January, 6th
Labour_day May, 1st
Carnival_monday -48
Mardi_gras -47
Ash_wednesday -46
Maundy_thursday -3
Good_friday -2
Easter_sunday 0
Easter_monday 1
Ascension_day +39
Whit_sunday +49
Whit_monday +50
Trinity +56
Corpus_christi +70
Assumption_day August, 8th
Penance_day Wednesday before Nov., 23rd
Christmas_day December, 25th
Boxing_day December, 26th

So now you can define a downtime for Carnival Monday using something like:

 define downtime {
    ...
    comment            Cheer up, lads
    downtime_period    carnival_monday 09:00-17:00
 }

7.17.3. Local holidays

Looking at the calendars of several countries there are a lot of holidays which only apply to a single country. Unfortunately some of these dates are on a weekday in a week within a month. You can already define these dates using "monday 3 february" or "monday -1 may" but you may want to use variables names as well. Defining these names and their corresponding calculations in a separate file and processing them enables you to do so. The default name for this file is holiday.cfg located in /usr/local/icinga/etc. The location can be altered using the option "-l".

We only picked three dates to give you the idea how to do it:

# example of local holiday definitions
# please don't use local characters
# variable names must not contain spaces
#
Presidents_day        day_in_week_of_month(2,1,3)
Spring_Bank_Holiday   day_in_week_of_month(5,1,-1)
Pentecote             date_easter(49)

There are two "functions" available to define these flexible dates:

So now you can define a downtime using something like:

 define downtime {
    ...
    comment            Don't shut down the cash machines
    downtime_period    spring_bank_holiday  09:00-17:00
 }

Please note that you have to specify the location of this file using the option "-l".

7.17.4. Entering downtimes

So far there is no way to enter the definitions via your browser so you have to use your favourite text editor to create the definitions. Sorry.

7.17.5. Planning downtimes

Once you have created a file holding the downtime definitions you will want to schedule the downtimes automatically. This can be done using the Perl script "sched_down.pl" being called from the crontab. The script itself requires the Perl module "Date::Calc".

The easiest way is to execute "/path/to/script/sched_down.pl". Adding the option "-h" will output some information:

   -c | --config=s     Icinga main config
                       default: /usr/local/icinga/etc/icinga.cfg
   -s | --schedule=s   schedule definitions
                       default: /usr/local/icinga/etc/downtime.cfg
   -l | --local=s      local holiday definitions
                       default: /usr/local/icinga/etc/holiday.cfg
   -m | --max_ahead=s  plan max. days ahead (default = 2)
   -f | --forecast=s   forecast next schedules
   -e | --examine=s    examine period and show next schedule
                       specify date and time instead like in downtime_period
   -t | --timestamp=s  specify deviating date/time
                       YYYYMMDDhhmi, YYYYMMDD, or hhmi
   -d | --debug=s      0|1|2|3 (default = 1)
   -h | --help         display this help

Note: Enabled debugging, forecasting, and/or examine will prevent that schedules
      are sent to the command pipe (downtimes are only calculated)!

Setting environment variables influences the behaviour:
- FAKE_DATE (YYYYMMDD): date deviating from current date
- FAKE_TIME (HHMM)    : time deviating from current time
- DEBUG (0|1|2|3)     : disables/enables debugging information
  0 = no debugging / cmds are sent to external command pipe!
  Note: command line options take precedence over environment variables 

All arguments are optional. Just to test the function of the script it might be helpful to use the "examine" option followed by a downtime period:

 /usr/local/icinga/bin/sched_down.pl -e "tuesday 20:00-21:00"

This will return a string similar to the actual command if the downtime is within the planning period (default two days) which can be altered using the option "-m". To test downtimes in the future you may set the environment variable FAKE_DATE (e.g. "FAKE_DATE=20130127") prior calling the script although it might be easier to use the option "-t".

There are two ways to execute the script:

Unless you get the downtimes on short notice this should be sufficient. The script will only plan non-existing downtimes so no harm will be done if it is called more often.

7.17.6. Converting downtime definitions

Steve Shipway has created files to plan downtimes via a CGI and schedule them for several Nagios versions a long time ago (see here).

The commercial Nagios version has added recurring downtimes as well but instead of using all of Steve's scripts they decided to take the scheduling script and write a new CGI which doesn't seem to be able to plan flexible downtimes (well, at least not in the 2011 VM).

The Perl script "sched_conv.pl" will try to convert files created by these two scripts mentioned above into a new file. You may want to call the script adding the option "-h" to get some help.

7.17.7. Files

You will find the perl scripts in tools/downtimes.