Scheduled Outages in OpenNMS

As described on the official documentation:

http://docs.opennms.org/opennms/releases/25.1.0/guide-development/guide-development.html#_scheduled_outages

This API requires two steps to have it working:

  1. Create a scheduled outage entry.

  2. Apply the created entry to one (or several) of the OpenNMS daemons through their packages (if applicable).

Each scheduled outage consist of the following:

a) A name

b) A recurrence type

c) A list of time range entries (the format of each entry depends on the type).

d) A set of node IDs and/or IP addresses

WARNING: When specifying both, node IDs and IP addresses, the IP addresses must appear first using the tag interface and then the node IDs using the tag node

The user should know prior start using this API the targets. As mentioned above, a user could use a set of node IDs and/or a set of IP Addresses. Unfortunately, it is not possible using categories, node labels, or other fields. That said, other ReST calls or SQL queries against the database might be needed to build the target list.

For the time range, several options are available, but they have a specific format. Failing using this format ends in OpenNMS rejects the entry.

Finally, the user must know which OpenNMS daemon is going to be affected by the scheduled outage in question. A user can assign it to one or many of the following options:

i) A poller package (affecting service availability and response time)

ii) A collection package (affecting data collection and threshold processing)

iii) A threshold package (affecting only threshold processing)

iv) Notifications. A general flag that affects all the notifications for the involved nodes (the concept of packages doesn’t exist here).

Now, let’s walk through the details.

Because there are several combinations, the following outlines several examples, as it is impossible to infer all the possibilities with a single one:

  1. Create a scheduled outage for nodes with IDs 10 and 11 that affect the data collection for the example1 package next month.

Because we’re talking about a specific time range, the JSON payload should be:

{
  "name": "sched-outage-example-01",
  "type": "specific",
  "time": [
    {
      "begins": "01-Jun-2017 00:00:00",
      "ends": "30-Jun-2017 23:59:59"
    }
  ],
  "node": [
    { "id": 10 },
    { "id": 11 }
  ]
}

Notes:

  • The name is up to the user, but as the name is part of the URL for specific calls, we suggest to keep it simple without spaces and special characters.
  • The format of the day has to be exactly as shown above to avoid rejections.
  • The time field expects an array so that multiple ranges can be specified, but all of them share the same type (in this case, specific).

Let’s say the above JSON exists on a file called sched-outage-example-01.json, here is how to create the scheduled outage:

curl -u admin:admin -H 'Content-Type: application/json' -d @sched-outage-example-01.json http://127.0.0.1:8980/opennms/rest/sched-outages

To verify if the scheduled outage exists:

curl -u admin:admin http://127.0.0.1:8980/opennms/rest/sched-outages/sched-outage-example-01

Now, at this point, nothing has been changed in terms of the OpenNMS operation. The intention of this use case is disabling data collection for the example1 package, which can be done with the following command:

curl -u admin:admin -X PUT  http://127.0.0.1:8980/opennms/rest/sched-outages/sched-outage-example-01/collectd/example1

Note: because the name of the packages is also part of the URL, make sure that all of them don’t have spaces or special characters. If there are special characters on either the name of the scheduled outage or the name of a given package, you have to URL encode them prior use them on the URL. Unfortunately, the user must have to take a look at the configuration files, as there is no way to know the name of the available packages through ReST.

  1. Create a scheduled outage for the node with ID 6, and the IP addresses 11.0.0.1 and 11.0.0.2 to run daily from 5 pm to 10 pm, affecting the poller package example1:
{
  "name": "sched-outage-example-02",
  "type": "daily",
  "time": [
    { "begins": "17:00:00", "ends": "20:00:00" }
  ],
  "interface": [
    { "address": "11.0.0.2" },
    { "address": "11.0.0.1" }
  ],
  "node": [
    { "id": 6 }
  ]
}

Notes:

  • It is possible to combine node IDs and IP addresses using the above format.
  • Careful with the ranges, as the type changes the behavior of the beings and ends tags.

To create it:

curl -u admin:admin -H 'Content-Type: application/json' -d @sched-outage-example-02.json http://127.0.0.1:8980/opennms/rest/sched-outages

To apply it:

curl -u admin:admin -X PUT  http://127.0.0.1:8980/opennms/rest/sched-outages/sched-outage-example-02/pollerd/example1
  1. Create a scheduled outage for the IP addresses 11.0.0.1 and 11.0.0.2 to run on every weekend, affecting notifications:
{
  "name": "sched-outage-example-03",
  "type": "weekly",
  "time": [
    {
      "day": "saturday",
      "begins": "00:00:00",
      "ends": "23:59:59"
    }, {
      "day": "sunday",
      "begins": "00:00:00",
      "ends": "23:59:59"
    }
  ],
  "interface": [
    { "address": "11.0.0.2" },
    { "address": "11.0.0.1" }
  ],
}

Notes:

  • This is an example with multiple entries on the time array (required in this example to cover 2 of the 7 days of the week, on a weekly outage).
  • The day is specified using its name (all lowercase).

To create it:

curl -u admin:admin -H 'Content-Type: application/json' -d @sched-outage-example-03.json http://127.0.0.1:8980/opennms/rest/sched-outages

To apply it:

curl -u admin:admin -X PUT  http://127.0.0.1:8980/opennms/rest/sched-outages/sched-outage-example-03/notifd
  1. Disable thresholds for hrstorage the first day of each month for ALL the nodes:
{
  "name": "sched-outage-example-04",
  "type": "monthly",
  "time": [
    {
      "day": "1",
      "begins": "00:00:00",
      "ends": "23:59:59"
    }
  ],
  "interface": [
    { "address": "match-any" }
  ]
}

Notes:

  • I’m introducing a new feature here. If you specify “match-any” as the value of the IP address, this scheduled outage applies for ALL the nodes on the database.
  • The day is specified using its number.

To create it:

curl -u admin:admin -H 'Content-Type: application/json' -d @sched-outage-example-04.json http://127.0.0.1:8980/opennms/rest/sched-outages

To apply it:

curl -u admin:admin -X PUT  http://127.0.0.1:8980/opennms/rest/sched-outages/sched-outage-example-04/threshd/hrstorage
  1. Remove entries.

Once the scheduled outage exists, the user can associate new packages, or remove packages from specific OpenNMS daemons. Of course, you can remove a scheduled outage when it is not needed anymore.

Let’s say that for the example1 package, a user changed his mind and wants to affect a poller package called my-routers instead of data collection. I should execute:

curl -u admin:admin -X DELETE  http://127.0.0.1:8980/opennms/rest/sched-outages/sched-outage-example-01/collectd/example1
curl -u admin:admin -X PUT  http://127.0.0.1:8980/opennms/rest/sched-outages/sched-outage-example-01/pollerd/my-routers

Finally, if the user wants to remove a whole scheduled outage:

curl -u admin:admin -X DELETE  http://127.0.0.1:8980/opennms/rest/sched-outages/sched-outage-example-01

That updates all the affected daemons when necessary.

2 Likes