Overview

OMD default:disabled
Hosts can be put in downtime by sending a simple HTTP-GET-request. It bypasses the Thruk login page and implements it's own security mechanism. It's mainly used by shutdown scripts which automatically set a downtime.

Directory Layout

Enabling the API

The downtime API is available since version 2.40. To enable this feature, execute the following step:

omd config set DOWNTIMEAPI on

Sending requests

Let’s say we have an OMD site bigdata running on server eudc-mon-p001. One of the monitored hosts has a configuration like this:

define host {
  host_name   ceph-008-mun
  address     10.129.3.44
  ...

Now we want to put it in downtime for an hour. This is as simple as:

curl -k -L "https://eudc-mon-p001/bigdata/api/downtime?host=ceph-008-mun&comment=maintenance&duration=60"

Of course this only works if this curl-command was executed on the host ceph-008-mun. The downtime API compares the originating IP address of the HTTP-request with the address-field of the host to be put in downtime.

If you want to set downtimes without logging into the host in question, you can use a (secret) token.

define host {
  host_name   ceph-008-mun
  address     10.129.3.44
  _DTAUTHTOKEN   supersecret234abc
  ...

By adding the dtauthtoken parameter to the URL, you can now execute the curl command wherever you want, for example on your central admin machine.

curl -k -L "https://eudc-mon-p001/bigdata/api/downtime?host=ceph-008-mun&comment=maintenance&duration=60&dtauthtoken=supersecret234abc"

The known parameters are:

  • host
    The name of the host to be put in a downtime. Be careful, this might not work with the local hostname. It must be equal to the host_name attribute of a nagios object definition.
    Internally, the downtime API communicates with Thruk. If there are multiple backends there may also be more than one Nagios host with this name. All of them will receive a downtime-command.
  • comment
    Whatever you want to see as a comment when you later look at the list of active downtimes. Be careful with special characters, you have to urlencode them.
  • duration
    The number of minutes the host should be in downtime.
  • dtauthtoken
    A secret token which must exist as a custom host macro named _DTAUTHTOKEN. This parameter is optional, it allows you to make an API-call from any location. Without it you can send GET-requests only from the host itself.
  • backend
    If Thruk has many backends and you know which one(s) monitor the host in question, you can improve execution times of the API. Without a backend parameter, Thruk first querys all of it’s backends looking for occurrences of the host. It can take a few seconds if you have hundreds of backends but usually this is not a problem.
Monitoring-Workshop 2017 12./13.9. Düsseldorf