Scheduled Outages in OpenNMS via ReST

As described on the official documentation, the ReST API endpoint to manage scheduled outages requires two steps to have it working:

• Create a scheduled outage entry.
• 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 name
• A recurrence type
• A list of time range entries (each entry format depends on the type).
• A set of node IDs and/or IP addresses

When specifying both, the node IDs and the 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 to use categories, node labels, or other fields. For that reason, the user would need other ReST calls (or run some SQL queries) to build the target list.

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

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

• A poller package (affecting service availability and response time)
• A collection package (affecting data collection and threshold processing)
• A threshold package (affecting only threshold processing)
• 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.

Create a schedule outage targeting nodes

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

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.

Create a schedule outage targeting nodes and interfaces

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

Create a schedule outage targeting interfaces

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

Disable specific thresholds for all nodes

Disable thresholds for the threshold group called 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

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.