Downtime - Creating

Endpoint to create downtimes on hosts and services

To set downtimes, you need to set downtime specific parameters and then choose the objects that the downtime will apply to.

Downtime Specific Parameters

Parameters for creating downtimes:

  • starttime - start time for downtime. Can be up to 1 hour in the past. Specify in epoch seconds or 'date and time strings' in the form of 'YYYY-MM-DD hh:mm:ss'. Required
  • endtime - end time for downtime. Specify in epoch seconds or 'date and time strings' in the form of 'YYYY-MM-DD HH:mm:ss'. Either this or duration must be set
  • duration - duration of downtime. Specify in 'Jira style', for example: "2h", "1d", "30m". Either this or endtime must be set. Must have a duration of at least 1 minute
  • comment - free text comment regarding downtime. The characters <>;\n will be stripped. Required
  • comment_prefix - if you do not use this, then Opsview will automatically prepend the object identifier to the start of the downtime comment - this means 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 string will be used as the prefix so all the downtimes will be grouped together. Note: This parameter does not work for hosts or host group downtimes

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

  • please ensure no spaces are left between the below fields or you may receive an error regarding the syntax
opsview@opsview-orchestrator:~$ cat /tmp/weekendowntime-api-downtime.json
{
        "starttime":"2020-01-17 17:00:00",
        "endtime":"2020-01-20 08:00:00",
        "comment":"testcomment-weekenddowntime"
}

You may apply this via a file (--content-file) as per the below example:

root@opsview-orchestrator:~#sudo su - opsview
opsview@opsview-orchestrator:~$ /opt/opsview/coreutils/bin/opsview_rest --username=admin --password=initial --data-format=json --pretty --content-file=/tmp/weekendowntime-api-downtime.json POST "downtime?hst.hostname=opsview

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 authentication information.

Downtime is created asynchronously, so the REST API will return as soon as the downtime has been submitted. There may be a small delay before the downtime is processed and stored in the database.

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

Object Selection

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 Opsview as downtime for each host and its services.

You can choose hosts or services using the same URL parameters as the Status REST API, with the following differences:

  • 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 the search criteria doesn't match any objects

Alternatively, you can search for objects using the following parameters, based on the object type you are searching for. This is called “object type specific parameters”.

  • Host Groups: (downtime will take effect for all sub host groups):
    • hg.hostgroupid
    • 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)
  • Hosts:
    • hst.hostid
    • 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)
  • Services:
    • svc.serviceid
    • 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: host and services will only be found if you have the appropriate access to the object

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:

{
    "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:%

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

Response

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 host groups, hosts and services that this downtime 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 below

/opt/opsview/coreutils/bin/opsview_rest –pretty –username=XXXX –password=XXXXXXXXXX \
  POST 'downtime?hg.hostgroupid=HOSTGROUPID&starttime=yyyy-mm-dd hh:mm:ss&endtime=yyyy-mm-dd hh:mm:ss&comment="<any comments here>"'