Welcome to docs.opsview.com

REST API: Downtimes

URL: /rest/downtime. This requires authentication. Requires DOWNTIMESOME or DOWNTIMEALL access.

Allowed Verbs
GET Lists downtime. Default will list all downtimes. See below for filtering options.
POST Create downtime.
PUT Not implemented.
DELETE Cancels downtime (if running) or deletes (if not yet started). If no objects are selected, nothing is deleted.

Access control

DOWNTIMEALL allows setting downtime to any object in Opsview.

DOWNTIMESOME allows setting of downtime to host or services based on the access object selection.

Note: You can only set downtime at the host group level with DOWNTIMEALL.

Note: If a user has access to some, but not all, services on a host and sets downtime for the host, then all services will also be marked in downtime. This means it is possible that a downtime has been set on a service by a user that does not have view access for.

Note: If a user has DOWNTIMEALL, but only VIEWSOME, the user could set downtime for objects that they cannot view.

Listing downtimes

Output of a list response:

{
    list => [
        {
            started    => 0,1, # 0 = not started yet, 1 = started
            start_time => ..., # If started, actual start time, otherwise scheduled start time.
            scheduled_end_time => ...,
            comment            => ...,
            author             => ...,
            objects => {
                hosts    => [ { hostname => ..., id => ... }, ],
                services => [ { id => ..., hostname => ..., servicename => ... }, ],
            }
        },
        ...
    ],
    summary => {
        rows         => ...,
        totalrows    => ...,
        allrows      => ...,
        page         => ...,
        totalpages   => ...,
        num_hosts    => ...,
        num_services => ...
    },
}

The list is ordered by scheduled start time, scheduled end time, comment data, author name.

You can filter this list based on the same parameters for filtering by service status.

Note: From Opsview 3.13.1, the format of the fields actual_start_time, scheduled_end_time, and start_time has changed to default to being epoch seconds. To have the old behaviour, use the URL parameter of “format_datetime=1”.

Creating a downtime

Attributes required for creating a downtime:

  • starttime - start time for downtime
  • endtime - end time for downtime
  • duration - jira style duration value for downtime. One of end_time or duration must be set for creation
  • comment - free text comment regarding downtime

These parameters can either be specified in the URL or via input to the REST API. For instance, in Perl format:

{
    comment   => ...,
    endtime   => ...,
    starttime => ...,
}

If the same parameters are found as input data and in the URL, the input data has priority.

The author of the downtime is taken from the user login information.

Downtime is created asynchronously, so the REST API will return as soon as the downtime submission is entered. There maybe a small delay before the downtime is listed in the database.

On successful submission of downtime, the response will be of the form:

{
    summary => {
        num_hostgroups => ...,
        num_hosts      => ...,
        num_services   => ...,
    },
    list => {
        hostgroups => [ { id => ..., name     => ... }, ],
        hosts      => [ { id => ..., hostname => ... }, ],
        services   => [ { id => ..., hostname => ..., servicename => ... }, ],
    }
}

This reflects the number of hostgroups, hosts and services that this downtime creation applied to.

In the event of a failure, the response will be:

{
    message => ...,
    detail  => ...,
}

Where “message” could be one of:

  • Error validating downtime parameters
  • No objects chosen for downtime creation (this could also appear if the user does not have access to the objects)
  • Errors setting downtime - some objects may have downtime set

Example: A typical command line example:

/usr/local/nagios/bin/opsview_rest –pretty –username=XXX –password=XXX POST “downtime?hg.hostgroupid=HOSTGROUPID&starttime=yyyy-mm-dd hh:mm:ss&endtime=yyyy-mm-dd hh:mm:ss&comment='<any comments here>'”

Deleting downtimes

Deleting a downtime will occur whether or not the downtime is currently in progress.

You delete downtimes based on the list of objects passed to the REST API. This will delete all downtimes on the objects unless you add in a start time and comment parameter, in which case only downtimes that match that start time and comment will be deleted.

The response will be the same format as the creation of downtime.

URL parameters (these have to be URL parameters as DELETEs do not allow content data):

  • start_time - start time of downtime. This can be in any format that setting a downtime parses. This is based on the scheduled start time.
  • comment - exact comment. Note, this is not the same as the comment entered when creating, as a prefix is added.

Downtime attributes

Attributes required for creating or filtering based on downtimes:

  • starttime - start time for downtime
  • endtime - end time for downtime
  • comment - free text comment regarding downtime

The author of the downtime is taken from the user login information.

The end time value can also be of a JIRA style format with a ”+” prefixed to denote the duration. See format of downtime for examples.

Optional parameters:

  • comment_prefix - if you do not use this, then Opsview will automatically prepend the object identifier to the start of the downtime comment. However, this means that there will be an audit log entry for each object, and the downtimes will not be grouped together. Setting this parameter will mean that only one entry will be in the audit log and this comment will be used as the comment prefix so all the downtimes for services will grouped together. Note: This parameter does not work for hosts or host group downtimes.

Object selection

Downtime is set against objects in Nagios® Core - hosts or services. Use the filter parameters below when POSTing to the REST API. There are different filtering parameters for GET requests.

When setting downtime in the REST API, we can set downtime against a host group, a host or a service. You can specify these objects through URL parameters. Note that although you can specify downtime for a host group, it is stored in Nagios Core as downtime for each host and its services.

You can choose hosts or services using the same URL parameters as the status API, with these rules:

  • No parameters means that no objects are found (status API returns everything if no parameters is passed).
  • Service objects will be returned if you have added a filtering on a parameter which looks for services, otherwise host objects are returned.
  • No errors are raised if objects are not found.

Alternatively, you can search for objects using the following parameters, based on the object type you are searching for.

Object Parameter Notes
hostgroup (downtime will take effect for all sub host groups) hg.hostgroupid Same as hostgroupid - this parameter takes priority.
hg.hostgroupname As you can have more than 1 host group with the same name in the hierarchy, this will apply for all of them.
host hst.hostid Same as hostid - this parameter takes priority.
hst.hostname
hst.hostgroupid This is only for the host group that the host belongs too. This is not based on the host group hierarchy.
hst.hostgroupname Only for host's hostgroup, not the hierarchy.
service svc.serviceid Same as serviceid - this parameter takes priority.
svc.hs Same as hs.
svc.hostgroupid
svc.hostgroupname
svc.hostid
svc.hostname Can use % as wildcard.
svc.servicename Can use % as wildcard.
svc.keywordid
svc.keywordname
svc.servicegroupname
svc.servicecheckid

Note: hosts and services will only be found if you have the appropriate access to the object. In addition, setting or deleting downtime for host groups requires DOWNTIMEALL access.

The basic rule is that if you are searching for multiple fields of the same type of object, then the search fields are AND'd together, but multiple values of the same field are OR'd together.

Duplicated host or services are ignored. Duplicate host groups are also ignored, but as downtime is set against leaf host groups, it is possible to set the downtime twice on the same host groups.

If you request a specific object (using hg.hostgroupid, hg.hostgroupname, hst.hostname, hst.hostid, svc.hs, svc.serviceid) and that object does not exist, an error is raised. For example:

{
    message => "Error when searching for objects",
    detail =>
      "Cannot find host with name nosuchhost; Cannot find host with id 3",
}

In no objects are found, an error is returned:

{ message => "No objects chosen for downtime creation" }

For example, URL parameters of:

...?svc.hs=hostA::service1&svc.serviceid=45&svc.hostname=hostB&svc.hostname=hostC&svc.servicename=HTTP&svc.servicename=Disk:%

…would select the service hostA::service1, the service with id=45, and all services called HTTP or Disk:% on hostB or hostC.

Paging

You can specify the following URL parameters to use paging.

  • rows - defaults to 50 entries in the downtimes list. Set to “all” to get all results
  • page - defaults to 1st page

Note: Due to the SQL joins that are used and the way that the result comes back in a nested fashion, it is possible to list a downtime that misses out the related host/service objects. If you need the precise list of objects based on the downtimes, the best thing to do is search by the downtime filters (comment, start_time, end_time) and set rows=0. This should always return the correct number of objects for the particular downtime. See OPS-1505.

How downtime is set

Downtime is set against objects and applies downwards, so if you:

  • set downtime for a host group, all lower host groups and their hosts and their services will have the same downtime associated.
  • set downtime for a host, all its services will also have the same downtime (even if the user does not have access to the services).
  • set downtime for a service, only that service will be set.

The downtime for the object is set at submission time. This means that if you set downtime to a host group and then add a new host to that host group, the new host will not have downtime set. This is also true for downtime on hosts with new services added.

Navigation
Print/export
Toolbox