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:

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.

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
 }

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".

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.

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.

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.

You will find the perl scripts in tools/downtimes.