Opsview REST API

Opsview has a REST API for updating the Opsview configuration using web service calls on the primary server. This uses the same underlying models and procedure as the web interface.

You should use the API to update the configuration data in Opsview as object updates are made within transactions (so a failure will rollback other related changes) and there is a lot of validation to ensure that the data is correct.

There is an official REST API Policy policy.

Connection

Connection to the REST API is via HTTP or HTTPS, based on how you have configured the Opsview web server. We recommend using HTTPS to encrypt the traffic between the client and the Opsview web server.

The API is hosted under the /rest URL. If you want to use a specific domain for the API, such as api.opsview.example.com, this could be achieved by configuring Apache to proxy a different site through to Opsview Web.

Authentication

The Opsview API authentication requires an authentication token. This is more secure than sending a password on every request because, after the initial login, all authentication is handled via a token. The token has an expiry time of 1 hour on it but every successful request will extend the expiry time.

You need to log in to Opsview to receive the authentication token. You then need to pass the authentication token for each request.

The flow is:

1. POST to /rest/login with a username and password. This can be with request parameters or as the request body in a data format (eg, if content-type is set to application/json and body is set to ”{'username':'admin','password':'initial'}”, then Opsview will use those parameters for login).
2. The response body will include the token value. This is, by default, returned as a Perl structure but, by changing the accept header, a different format can be returned (eg JSON or YAML). The token is 40 hexadecimal characters. For example, for JSON, you will get

{
    "token":"bdd6ad8e242a993107f13260a7007e38384ce4aa"
}

3. For all subsequent requests, add the following headers. Replace the username and tokenstring appropriately:

X-Opsview-Username: username
X-Opsview-Token: tokenstring

4. If there are any errors, an appropriate status code will be set and the body will contain the appropriate data type with

{
    message => "error string"
}

To reduce the possibility of a CSRF attack, the authorisation token is not implemented as a cookie.

Data exchange

You can exchange data between the web service and your script by using either JSON, serialized Perl objects, or XML.

Use Content-Type headers to change the input and output data. Currently tested for:

• application/json (JSON)
• text/x-data-dumper (Perl format)
• text/xml (XML format. More details on XML Serialisation.)

You should always set a Content-Type header and the Accept header should be set to the same value. Alternatively, for GET requests only, it is possible to force a content type using a URL parameter, for example: “content-type=application/json”.

Output as strings

With JSON output, all values are returned as strings. Be aware that in Javascript, if you need to add two strings together numerically, you will need to force a conversion to integers, otherwise a ”+” is considered to be string concatenation. Use the following: ”(value1-0)+(value2-0)”.

Date and time values as epoch seconds

All date and time values are returned as epoch seconds (as a string), which by definition is always UTC.

It is possible to format the date/time value based on the time zone of the Opsview server by using the URL parameter, “format_datetime=1”. This will return a string of the format “YYYY-MM-DD HH:mm:SS”.

Request

Requests consist of five parts:

• A URL
• URL parameters
• A verb (one of PUT, POST, GET, DELETE)
• Headers, to change behaviour of the input and output data
• Data, if necessary

If you cannot use a verb, it is possible to use POST and then tunnel the required verb through using a POST parameter (x-tunneled-method).

Response

Responses consist of two parts:

• A status code
• Data, if necessary

Always returning a status 200

Opsview's REST API is implemented with pure REST principles, so the status code of the response reflects the error (eg, 401 for authentication denied). However, sometimes you always want a 200 response back, for instance, if you are using JSONP.

If you set a URL parameter of “alwaysReturn200=1”, then the status will always be 200 and there will always be REST data, which will be added into the keyword, “rest”:

{
    "rest": "NORMALRESTDATA",
    "status": "ACTUALSTATUS"
}

If there is no data, then rest will be set to null.

Errors

If there was an error, a corresponding status code will be set. Data will be sent with the format in the form of:

{
    message => "Text explaining the error",
    detail  => "Text with further detail. This may not exist",
}

Note: The content returned may be in a different format than the one requested. For instance, invalid data structures (400 bad request) could return content-type text.

Common errors

400: Bad Request

This can mean that the input parameters cannot be parsed. There should be more information in the content.

If the contents shows something like:

Content-Type application/json had a problem with your request.
***ERROR***
malformed JSON string, neither array, object, number, string or atom, at character offset 180 (before "],\n      "all_servi..."),
 <$fh> line 21.

Then this means there is some invalid JSON data. JSON input is set to “relaxed”, so additional commas at end of lists are valid.

401: Unauthorised

This means you have not authenticated to the REST API, ie. not logged in.

404: Not Found

You will get this error if you try to access a URL that does not exist.

Examples

opsview_rest

• You can use /opt/opsview/coreutils/bin/opsview_rest to communicate with the REST API. For example:

  opsview_rest --username=admin --password=initial GET config/host/1
  

  This will return back the complete serialisation of the host. Add ”--data-format=json” to change the data format to JSON. Add ”--pretty” to get nicely formatted output.
• You can get the output to edit and put back again:

  opsview_rest --username=admin --password=initial --data-format=json --pretty GET config/host/1 > host.json
  vim host.json
  opsview_rest --username=admin --password=initial --content-file=host.json --data-format=json --pretty PUT config/host/1
  

• To show all performance statistics for the “unix swap” metric:

  opsview_rest --username=admin --password=initial --pretty GET '/rest/status/performancemetric/?servicename=Unix Swap'
  

• To show all performance statistics for the host, “opsview”:

  opsview_rest --username=admin --password=initial --pretty GET /rest/status/performancemetric/?hostname=opsview
  

• To show the “load average” metric from host, “opsview”:

  opsview_rest --username=admin --password=initial --pretty GET '/rest/status/performancemetric?order=metricname&order=hostname&metricname=load1&hostname=opsview'
  

• To add a host, you need to create a JSON file with the information — you can perform a GET on an existing host to see the template. Eg.,

  {
    "hostgroup": {
        "name": "Production"
    },
    "hosttemplates": [
        {
            "name": "OS - Linux Advanced"
        }
    ],
    "icon": {
        "name": "LOGO - Opsview",
        "path": "/images/logos/opsview_small.png"
    },
    "ip": "newhost.fqdn",
    "monitored_by": {
        "name": "Collector Cluster",
        "ref": "/rest/config/monitoringcluster/3"
    },
    "name": "newhost",
    "other_addresses": "192.168.12.1"
  }
  

  Then upload the data via the API to create the host:

  opsview_rest --user=admin --password=initial --pretty --data-format=json --content-file=/path/to/newhost.json PUT config/host
  

• To delete a host via its ID:

  opsview_rest --username=admin --password=initial --pretty DELETE config/host/<ID>
  

• To perform a reload of Opsview:

  opsview_rest --username=admin --password=initial --pretty POST reload
  

• opsview_rest can also make use of an authentication token. To create the token file the first login must use a password:

  opsview_rest -u admin -p initial -t /path/to/opsview_restapi_token GET info
  

  Thereafter, the password does not need to be supplied:

  opsview_rest -u admin -t /path/to/opsview_restapi_token GET info
  

  Upon every use, the token is refreshed and will expire after 60 minutes.

  Unix tools

  You can use the unix tools curl and wget to query Opsview via the REST API. To login to the REST API using curl:

  curl -H 'Content-Type: application/json' -X 'application/json' -X POST -d '{"username":"admin","password":"initial"}' http://localhost/rest/login > logindata
  

  To parse the response, we recommend using jq, a lightweight tool to retrieve specific parts of a JSON file. To extract the token, use:

  token=`jq -r .token logindata`
  

  You can then use $token:

  curl -H 'Content-Type: text/json' -H 'text/json' -H 'X-Opsview-Username: admin' -H "X-Opsview-Token: $token" -X GET 'http://localhost/rest/event?rows=2' > eventdata
  

  (Note text/json is also valid for requesting JSON response)

  To list out the first record in the response:

  jq '.list[0]' eventdata
  

  Another REST API usage, for example, to set downtime, is:

  curl -H 'Content-Type: application/json'-H application/json' -H 'X-Opsview-Username: admin'-H admin' -H "X-Opsview-Token: $token"-X $token" -X POST -d '{"starttime":"2016-05-26 17:00:00","endtime":"2016-05-26 17:15:00","comment":"Test downtime"}'"http://localhost/rest/downtime?hst.hostgroupid=1"| jq .list
  

  This will set downtime at the specified times for all hosts that are in hostgroup id 1. Note, we have used jq directly in a pipe to list the changed items.

  If you are using wget instead of curl, the parameters are slightly different:

  wget -q -O logindata --header="Content-Type: application/json"--method=POST --body-data='{"username":"admin","password":"initial"}' http://localhost/rest/login
  

To post an acknowledgement, the following example can be tailored:

curl -k -H 'Accept: application/json' -H 'Accept: application/json' -H "Content-type: application/json" -H "X-Opsview-Username: admin" -H "X-Opsview-token: $token" -X POST -d '{"comment":"test","notify":"0","sticky":"0"}' 'https://localhost/rest/acknowledge?hostname=webdev&servicename=CPU%20statistics'

export_host_template

This is a small script, /opt/opsview/coreutils/utils/export_host_template, which will export a specific host template in JSON format, including related service checks and their service groups. You can then take the exported file and import using import_json. For example:

utils/export_host_template --username=admin --password=initial "Network - Base" > /tmp/json
utils/datatidy /tmp/json
vim /tmp/json # Edit the file to change the name of the host template to NEW Network - Base
bin/import_json --username=admin --password=initial /tmp/json

This will create the service group, if it doesn't already exist. It will also update or create service checks that have the given name. Then, it will update or create the host template with the given data.

Note: The importing is based on the name of objects, so if an object already exists with the same name, then it will be updated with the data.

Interface

The REST API is separated into different sections:

• Configuration - for changes to Opsview configuration data
• Downtime - for changes to scheduled downtimes
• Status - for querying status information
• Runtime - for querying objects that are being monitored live
• Acknowledge - for acknowledgements
• Rechecks - for re-checking a host or service
• Graph - for graph data
• Event - for event data
• Notes - for static note information
• Query Host - for querying a host for SNMP information
• Detail - for getting detail about a specific host/servicecheck
• Test Service Check - for testing how servicechecks respond
• Notification Method - for getting sent notification information

Other common endpoints are listed below.

API version information

URL: /rest

Authentication not required.

• GET - gets version information
• POST,PUT,DELETE - unimplemented

This returns back information about the API. For example, this would respond with:

{
    api_version     => "3.0100005360",
    api_min_version => "2.000",
    easyxdm_version => "2.4.15.118",
}

api_version and api_min_version are floating point numbers.

Clients should check that api_min_version is less than or equal to the version that the client was written for. api_min_version will be incremented if backwards compatibility has been broken.

The easyxdm_version information is used for interfacing to EasyXDM's cross domain communication. Load /restxdmxhr.html?version=VERSION to initiate the EasyXDM interface.

Opsview information

URL: /rest/info

Requires authentication.

• GET - gets version information
• POST,PUT,DELETE - unimplemented

This returns back information about Opsview. For example, this would respond with:

{
    opsview_version        => "4.5.0",
    opsview_build          => "4.5.0.16122",
    opsview_edition        => "commercial",
    opsview_name           => "Opsview",
    server_timezone        => "UTC",
    server_timezone_offset => 0,
    uuid                   => "5B40A354-90C4-11DE-8C65-487C69EFFEC7",
    hosts_limit            => "1000",
}

opsview_name is based on the top level in the host group hierarchy.

opsview_edition is a string, which could be either community, enterprise or commercial.

server_timezone_offset is the number of seconds that this server's time zone is, relative to UTC. This could be a negative value. This is based on the current time, so you will get a different offset if you are currently in daylight saving time. This is a simple calculation to work out differences between browser time and server time, taking into account the time zone differences.

hosts_limit is the maximum number of hosts that you can add to Opsview based on your Opsview subscription. If the value is an empty string, then this means there is no limit on the number of hosts. This field will only exist if the current user can see all the hosts in the system (otherwise this user must have a subset of CONFIGUREHOSTS and thus cannot have a complete list of all hosts).

Logging in to the API

URL: /rest/login

• GET - unimplemented
• POST - get session token. Pass in username and password
• PUT - unimplemented
• DELETE - if session token is valid, deletes from session list, effectively a logout

If a token cannot be generated, a 503 HTTP status code will be returned, with the text, “Error creating session token after 5 attempts”.

If you can pass the parameter, “include_one_time_token=1”, an extra field will be returned in the response with a one time token for logging into the web user interface. You can then log in to http://opsview.example.com/login?login_username=n... This token expires after 10 minutes and requires it come from the same IP address as the REST API request. Once logged in, the token is removed from the system. Access through the browser then works via the authentication cookie as normal.

Example response:

{
    "one_time_token": "e3fab615c06d158b0795cef36ce56408ce7ea6c1",
    "token": "7cd5652f7bfde4220211d063c166b263160a7d52"
}

If you can pass the parameter, “include_user_data=1”, a “user_data” field will be returned in the response. This will contain the data from the /rest/user call.

Logging in to the API via AuthTkt

URL: /rest/login_tkt

• POST - get session token. Pass in username
• GET,PUT,DELETE - unimplemented

Required parameter:

• username

This acts like /rest/login, but authenticates a user based on their auth_tkt cookie. This allows a web browser which has already been authenticated to connect to the REST API. The username is still required to be passed in as a secondary check so that knowing the cookie is not sufficient to gain access to the API.

Logout

URL: /rest/logout

• POST - deletes the session
• GET,PUT,DELETE - unimplemented

User information

URL: /rest/user

• GET - returns user information for the currently authenticated user
• POST,PUT,DELETE - unimplemented

This returns information about the user. Example response:

{
    "access_list": {
        "ACTIONALL": 1,
        "ADMINACCESS": 1,
        "VIEWALL": 1,
        ...
    },
    "fullname": "Admin user",
    "language": "",
    "name": "admin",
    "realm": "local",
    "role": "Administrator"
}

Initiating an Opsview reload

URL: /rest/reload

• GET - gets status of reload
• POST - initiates a synchronous reload. Returns 200 if reload completed. Will return 400 with error messages if reload fails. Will return 409 if a reload already in progress
• PUT - unimplemented
• DELETE - unimplemented

Requires RELOADACCESS.

Parameters:

• asynchronous - if set to 1, an asynchronous reload will be run. Use a GET request to poll to see if the reload has completed. Default 0
• changelog - if a POST request and changelog is enabled, you must set the text to save otherwise an error will occur

Returned data:

• server_status - this is the state of the server
  • 0 - server running, with no warnings
  • 1 - server reloading
  • 2 - server not running
  • 3 - configuration error or critical error
  • 4 - warnings exist
• configuration_status - this is the state of the configuration
  • uptodate - all configuration changes have been applied
  • pending - at least one configuration change requires a reload
• average_duration - number of seconds a reload normally takes, rounded up to nearest 10 seconds
• lastupdated - epoch time for last configuration update
• auditlog_entries - number of audit log entries since last backup. This could be undef
• messages - array of messages, where each message is a hash (or dictionary) of strings

If a reload is already in progress then the status code will be set to 409 with returned data of:

• server_status - set to 1
• messages - set to [ “Reload already running” ]

Example request/response:

$ opsview_rest --username=admin --password=initial --pretty GET reload
{
   "auditlog_entries" : "0",
   "average_duration" : "30",
   "configuration_status" : "uptodate",
   "lastupdated" : "1519680052",
   "messages" : [
      {
         "detail" : "Missing required variable EMAIL for contact admin for notification method Email - ignoring this notification",
         "monitoringserver" : "Master Monitoring Server",
         "severity" : "warning"
      }
   ],
   "server_status" : "4"
}

Logging

All REST failures are logged to syslog.

This will show a line like:

REST response (ERROR=403): GET /rest/config/monitoringcluster?cols=-monitors Data:{ message => "Access denied" }

If you want to log all REST requests and responses, uncomment this in /opt/opsview/webapp/etc/Log4perl.conf:

log4perl.logger.Opsview.Web.ControllerBase.REST=DEBUG

It can take up to 30 seconds after the file is saved, to start logging. Note that logging may increase the response times of Opsview Web.

We will mark particular aspects of Opsview as having an Application Programming Interface (API). This means:

• We will publish documentation about the API on how to use it.
• We will extensively test the API to ensure no regressions exist.
• We will maintain the API and fix any bugs against it.
• We try not to make unnecessary changes to the API.
• If we make any changes to the API, it will be documented on this site.

From time to time, we may deprecate certain API functionality. This means:

• We will not be adding any new features.
• We will not fix any bugs against it.
• We will mark documentation to say that it is deprecated.
• We will remove the code in future.
• We recommend new code is not developed against it.
• We will provide a migration path to an newer API.

The preferred data formats is to use JSON or perl as this preserves all the data in the native formats, as well as being much smaller in size. However, there is the ability to communicate with the Opsview REST API using XML.

The rules for data conversion are:

• Values that are simple scalars can be defined as attributes.
• Items that have a list of objects will have <item></item> marked around it (instead of an array of items).
• If the list of items is empty, an attribute of isEmpty=1 is required (as you cannot have an empty array in XML).
• When referencing foreign objects, there will be a <name></name> to define the name of the object.
• Values what are undefined will have an attribute of isNull=1.

Example List Data

An example response is:

<opsview>
  <list>
    <item name="cisco"
          alias=""
          check_attempts="2"
          check_interval="0"
          enable_snmp="0"
          flap_detection_enabled="1"
          id="7"
          ip="192.168.10.20"
          nmis_node_type="router"
          notification_interval="0"
          notification_options="u,d,r"
          other_addresses=""
          rancid_connection_type="ssh"
          ref="/rest/config/host/7"
          retry_check_interval="1"
          snmp_community="shouldnotcreate"
          snmp_version="2c"
          snmpv3_authpassword=""
          snmpv3_privpassword=""
          snmpv3_username=""
          uncommitted="1"
          use_mrtg="0"
          use_nmis="0"
          use_rancid="0">
      <check_command name="slow ping"
                     ref="/rest/config/hostcheckcommand/1" />
      <check_period name="24x7"
                    ref="/rest/config/timeperiod/1" />
      <event_handlers isEmpty="1" />
      <exceptions isEmpty="1" />
      <excludedservicechecks isEmpty="1" />
      <hostattributes isEmpty="1" />
      <hostgroup name="Leaf"
                 ref="/rest/config/hostgroup/4" />
      <hosttemplates>
        <item name="Cisco Mgt"
              ref="/rest/config/hosttemplate/3" />
      </hosttemplates>
      <icon name="SYMBOL - Environment Monitor" />
      <keywords>
        <item name="alphaearly"
              ref="/rest/config/keyword/6" />
        <item name="cisco"
              ref="/rest/config/keyword/2" />
        <item name="cisco_gp1"
              ref="/rest/config/keyword/3" />
      </keywords>
      <monitored_by name="Master Monitoring Server"
                    ref="/rest/config/monitoringclusterr/1" />
      <notification_period name="24x7"
                           ref="/rest/config/timeperiod/1" />
      <parents>
        <item name="cisco"
              ref="/rest/config/host/7" />
      </parents>
      <rancid_password isNull="1" />
      <rancid_username isNull="1" />
      <rancid_vendor isNull="1" />
      <servicechecks>
        <item name="Another exception"
              ref="/rest/config/servicecheck/82" />
        <item name="Coldstart"
              ref="/rest/config/servicecheck/79" />
        <item name="Interface"
              ref="/rest/config/servicecheck/95" />
        <item name="snmp poll"
              ref="/rest/config/servicecheck/83" />
        <item name="Test exceptions"
              ref="/rest/config/servicecheck/81" />
      </servicechecks>
      <snmpv3_authprotocol isNull="1" />
      <snmpv3_privprotocol isNull="1" />
      <timed_exceptions isEmpty="1" />
    </item>
    ...
  </list>
  <summary allrows="22"
           page="1"
           rows="2"
           totalpages="11"
           totalrows="22" />
</opsview>

The following verbs are allowed:

• GET - retrieve either an object information or a list of objects.
• PUT - update. Will also create if the object does not currently exist. Will return the object after update.
• POST - create when POSTed to an objecttype URL, clone when POSTed to an object URL. However, creations will update if the object already exists. Will return the object after creation.
• DELETE - delete object. Will return a hash with response {“success”:1}

The data passed to the API is in the form of key/value pairs. The key is a string, but the value can be a string, an array or an associative hash. Examples are below.

When updating data, keys that are unexpected are silently ignored.

Values in an array are expected to be related objects in a hash format. If the related object is not in a hash format, you will get an HTTP 400 error with the message: Error when parsing data, and detail: Not a HASH: name.

An error will be raised if related objects cannot be found.

List endpoints can take parameters to alter the data returned. These are:

• rows - number of rows to return. Defaults to 50. If rows=0, then only a summary will be returned. If rows=all, all rows are returned.
• page - page number to return. Defaults to 1
• cols - which columns to return. This is a comma separated list. Only valid columns per object will be used. If no columns specified, will use all available columns for this object. Can prefix with a ”+” to add optional columns to the default list (Note: you may have URL encoding issues if run on the command line - use %2B to ensure that the symbol is passed to Opsview correctly). Can prefix column name with a ”-” to remove the column from the available list.
• s.{columnname} - will search using LIKE for parameter. Add % for wildcards if required - this should be %25 to be encoded in the URL (see this article regarding URLs and encoded values). If parameter is specified multiple times, will be considered as an OR for that column. If more than 1 column is specified, will consider to be an AND with other columns
• s.{relation}.{columnname} - as above but it will search on related items. See hosts for an example
• order - will sort the results based on the order specified. See below for more information
• json_filter - this allows complex searching of fields. See below for more information
• in_use - if set to 1, then each object will return in_use either 0 or 1 depending on if the object is being used by related objects

You can specify a search criteria in JSON format using the json_filter URL parameter. The contents of this is converted to a perl hash format, which is expected to be in SQL::Abstract format.

For instance, to search for all objects where id is not equal to 1, you would have:

....?json_filter={"id":{"!=":1}}

And to search for all objects who's name contains 'collector' or FQDN contains 'der', you would have:

....?json_filter={"-or":[{"name":{"-like":"%25collector%25C"}},{"ip":{"-like":"%25der%25"}}]}

(note the '%' SQL search regexp is url encoded to be %25)

Note: As this option is more low level, you may cause errors when invoking the API. If there are errors with the search, you will get a message of Error executing search with detail giving the full reason.

Note: Only the current table search column comparisons are supported at the moment. All column names are prefixed with me., which means only a search on the current table is possible.

Ordering of results is based on the “order” parameter. The value for this parameter can be a single entity or comma separated list of entities to order by.

Ordering will be performed in order from left to right. For example, to order the results by hosts with SNMP enabled then name, the order should be “snmp_enabled,name”.

The default order is ascending, but can be changed to descending by appending the criterion with “_desc”. For example, to reverse order by name, “order=name_desc”.

It is possible to order by sub-entity, ie. entities that don't have a straight value, such as enable_snmp, name, ip, but rather entities that have multiple values: hostgroup, hosttemplates, servicechecks, etc. To do this, the criterion must be the name of that value, followed by a fullstop, then the entity to order by. For example, to order the hosts by host group name, order should be “hostgroup.name”.

If the request was successful, the response will be a status code of 200. If data is requested, this will be in the content in the requested format.

The response format for a single object is (in JSON format):

{
   "object" : { ... }
}

The response format for a list of items is (in JSON format):

{
    "summary": {
        "rows": "30",
        #This is the number of rows in the response.If this equals allrows,
        then you have all results "page": 1,
        #Current page number "totalrows": "100",
        #This is the count of all the rows based on the search parameters "totalpages": 4,
        #Based on the pages and the number of rows per page,
        this is the total number of pages "allrows": "153",
        #This is the count of all rows
        for this datatype(restricted by user access, eg hosts)
    },
    "list": [{
            "ref": "/rest/config/servicecheck/47",
            "name": "/",
            "id": "47",
            "description": "Utilisation of / partition"
        },
        ....
    ]
}

The object hash within a list is the same as a single object.

The value for the ref key provides a way of accessing the related object.

If there was an error, an appropriate status code will be set. Data will be sent with the format in the form of:

{
   message => "Text explaining the error",
   detail => "Text with further detail. This may not exist"
}

Note: The content returned maybe in a different format than the one requested. For instance, invalid data structures (400 bad request) could return content-type text.

The Rest API may only return part of the error text; full details of the error will always be logged to the backend log file. To enable more detailed error information to be returned to the caller, add the following lines to your opsview_web_local.yml file and restart opsview-web:

ControllerBase::REST:
  include_error_detail: 1

Common Errors

400: Bad Request

This can mean that the input parameters can not be parsed. There should be more information in the content.

If the contents shows:

Content-Type application/json had a problem with your request.
***ERROR***
malformed JSON string, neither array, object, number, string or atom, at character offset 180 (before "],\n      "all_servi...") at <$fh> line 21.

Then this means there is some invalid JSON data. JSON input is set to “relaxed”, so additional commas at end of lists are valid.

URL: /rest/config/{object_type}

• GET - list object type. Can pass in search attributes
• POST - add a new object or a list of object type
• PUT - create or update (based on unique keys) object or a list of objects
• DELETE - unimplemented

URL: /rest/config/{object_type}/{id}

• GET - get object details
• POST - clone this object with merged incoming data to create new object
• PUT - update this object's details
• DELETE - delete object

URL: /rest/config/{object_type}/exists?name={name}

• GET - get object existential status

Updating a single object

When POST or PUTting a single object, the API expects a hash input with key value pairs. If successful, the API will return back the new serialised object.

All ref attributes are ignored when updating - the ref key is for clients that may want further information about the foreign object.

Updating a list of objects

When POST or PUTting a list of objects, the API expects a hash with a key of list which is an array of hash objects. Each object will then be POST or PUT in turn.

If successful, the data returned will be of the format:

{
   "objects_updated" : 3
}

There is an extra parameter that can be used:

• synchronise - this means that any objects left after the individual PUTs will be deleted

The whole request is wrapped in a transaction. If there is a failure for any item, a rollback will occur and no changes will have been made to the system. The response will be:

{
   message:"Rollback. Error trying to synchronise object: 2",
   detail:"detail about the error",
   objects_updated:0
}

Examples

Updating Multiple Service Checks

The restapi can be used to update multiple servicechecks in one go:

• Obtain the list of check to be modified and store in a file, i.e. all service checks with 'foo' in the name.

opsview_rest --username=USER --password=PASS --pretty --data-format=json GET 'config/servicecheck?json_filter={"name":{"-like":"%25foo%25"}}' > checks.json

• Edit the checks.json file as necessary.
• Import the contents of the file back into Opsview.

opsview_rest --username=USER --password=PASS --pretty --data-format=json --content-file=checks.json --pretty PUT config/servicecheck

Note: the ID's within the checks.json file must be left unchanged else new checks will be created, not current checks updated.

Note: Amending service check names could lose historical (graphing) information

Determining If A Host Exists

To see if the host 'foo' already exists:

opsview_rest --username=USER --password=PASS GET 'config/host/exists?name=foo'

Will return ”{'exists' ⇒ '0'}” if the host does not exist, ”{'exists' ⇒ '1'}” if it does.

Object type: attribute

Example GET:

{
   "object" : {
      "name" : "PROCESS",
      "id" : "6",
      "arg1" : "",
      "arg2" : "",
      "arg3" : "",
      "arg4" : "",
      "value" : "",
      "servicechecks" : [
         {
            "ref" : "/rest/config/servicecheck/92",
            "name" : "Processes"
         },
         {
            "ref" : "/rest/config/servicecheck/93",
            "name" : "Windows Processes"
         }
      ]
   }
}

Note: When saving attributes, you cannot add a host attribute nor amend the list of service checks using an attribute. If you want to amend a service check so that it is no longer using multiple attributes, you have to edit the service check itself.

Note: arg1 to arg4 and value are available from Opsview 3.11.0.

Object type: contact

Example contact:

{
    "object": {
        "language": "",
        "servicegroups": [{
            "ref": "/rest/config/servicegroup/2",
            "name": "freshness checks"
        }, ],
        "all_servicegroups": "1",
        "name": "admin",
        "encrypted_password": "$apr1$dEX5UaQz$D6fCyI197d33YcQQqe1Yj.",
        "variables": [{
            "value": "1",
            "name": "RSS_COLLAPSED"
        }, ],
        "all_hostgroups": "1",
        "fullname": "admin",
        "keywords": [{
            "ref": "/rest/config/keyword/8",
            "name": "allservicechecks"
        }],
        "description": "Initial admin user",
        "hostgroups": [{
            "ref": "/rest/config/hostgroup/4",
            "name": "Build"
        }, {
            "ref": "/rest/config/hostgroup/2",
            "name": "Monitoring Servers"
        }, ],
        "notificationprofiles": [{
            "host_notification_options": "u,d,r,f",
            "servicegroups": [],
            "ref": "/rest/config/notificationprofile/4",
            "name": "Default",
            "all_servicegroups": "1",
            "all_hostgroups": "0",
            "hostgroups": [{
                "ref": "/rest/config/hostgroup/5",
                "name": "Leaf2"
            }],
            "service_notification_options": "w,c,r,u,f",
            "id": "4",
            "notification_level": "1",
            "uncommitted": "1",
            "notification_period": {
                "ref": "/rest/config/timeperiod/1",
                "name": "24x7"
            }
        }],
        "realm": "local",
        "id": "1",
        "role": {
            "ref": "/rest/config/role/10",
            "name": "Admin"
        },
        "uncommitted": "0"
    }
}

Note: The reference to the notificationprofile object type is not currently available.

Object type: host

Example host response:

{
   "object" : {
      "snmpv3_privprotocol" : null,
      "flap_detection_enabled" : "1",
      "hosttemplates" : [
         {
            "ref" : "/rest/config/hosttemplate/4",
            "name" : "Blank"
         }
      ],
      "keywords" : [],
      "check_period" : {
         "ref" : "/rest/config/timeperiod/3",
         "name" : "nonworkhours"
      },
      "hostattributes" : [
         {
            "arg1" : null,
            "arg2" : null,
            "arg3" : null,
            "arg4" : null,
            "value" : "/remote",
            "name" : "DISK"
         },
         {
            "arg1" : null,
            "arg2" : null,
            "arg3" : null,
            "arg4" : null,
            "value" : "opsviewd",
            "name" : "PROCESS"
         }
      ],
      "id" : "22",
      "notification_period" : {
         "ref" : "/rest/config/timeperiod/1",
         "name" : "24x7"
      },
      "notification_options" : "d,r",
      "name" : "monitored_by_cluster",
      "rancid_vendor" : null,
      "hostgroup" : {
         "ref" : "/rest/config/hostgroup/5",
         "name" : "Leaf2"
      },
      "enable_snmp" : "1",
      "event_handler" : "",
      "monitored_by" : {
         "ref" : "/rest/config/monitoringcluster/3",
         "name" : "Cluster"
      },
      "alias" : "Host to be monitored by collector",
      "uncommitted" : "1",
      "parents" : [],
      "retry_check_interval" : "4",
      "icon" : {
         "name" : "SYMBOL - Wireless network",
         "path" : "/images/logos/wireless_small.png"
      },
      "ip" : "monitored_by_clusterip",
      "use_mrtg" : "0",
      "servicechecks" : [
         {
            "ref" : "/rest/config/servicecheck/45",
            "name" : "Check Loadavg",
            "exception":"-w 5,5,5 -c 9,9,9",
            "timed_exception":null,
            "event_handler":null,
            "remove_servicecheck":0,
         },
         {
            "ref" : "/rest/config/servicecheck/4",
            "name" : "DNS",
            "exception":"--other --args",
            "timed_exception":null,
            "event_handler":null,
            "remove_servicecheck":1,
         },
         {
            "ref" : "/rest/config/servicecheck/6",
            "name" : "HTTP",
            "timed_exception":{
                "timeperiod" : { "name" : "workhours" },
                "args" : "--url=/about -w 2 -c 4",
            },
            "exception":null,
            "remove_servicecheck":0,
            "event_hander":"restart_http",
      ],
      "use_rancid" : "0",
      "nmis_node_type" : "server",
      "snmp_version" : "2c",
      "use_nmis" : "1",
      "rancid_connection_type" : "ssh",
      "snmpv3_authprotocol" : null,
      "rancid_username" : null,
      "rancid_password" : null,
      "check_command" : {
         "ref" : "/rest/config/hostcheckcommand/7",
         "name" : "NRPE (on port 5666)"
      },
      "check_attempts" : "15",
      "check_interval" : "25",
      "notification_interval" : "60",
      "snmpv3_privpassword" : "",
      "snmpv3_username" : "",
      "other_addresses" : "",
      "business_components" : []
   }
}

Optional parameters:

• is_parent=1 — this will only list hosts that are parents.
• include_ms=1 — this will add extra attributes in the response for each host: is_master=1 if this host is used as the master/primary server; is_ms=1 if this host is used as a collector (from Opsview 6) or monitoring server (master or slave, in Opsview 5 and below); is_netflow=1 if this host is used as a NetFlow source. Note that id must be one of the columns returned to identify the monitoring server.
• include_encrypted=1 — If set, Opsview will return the SNMP community, SNMPv3 authentication password, or SNMPv3 privacy password as encrypted_snmp_community, encrypted_snmpv3_authpassword and encrypted_snmpv3_privpassword respectively. This could return the empty string to mean no password is set.

There are additional options for filtering by related objects:

• s.hosttemplates.name - will search for hosts that have this host template. If this parameter is repeated, will list all hosts that have any of these host templates. If you want to find hosts that have all of the host templates, you need to include the c.hosttemplates.name=all parameter.
• s.hosttemplates.id - same as above, searching host templates by id. c.hosttemplates.id=all will mean list hosts will all the requested host templates.
• s.monitored_by.id - search for hosts that are monitored by this monitoring server by id.
• s.business_components.id - search for hosts related to this business component. Can be repeated for any of the business_components. Use c.business_components.id=all to require all the business_components.

When modifying a host, the encrypted SNMP community, and encrypted SNMPv3 authentication and privacy passwords can be set by passing encrypted_snmp_community, encrypted_snmpv3_authpassword, and encrypted_snmpv3_privpassword, respectively. If snmp_community, snmpv3_authprotocol, and/or snmpv3_privpassword are passed, then those elements will be set to those new values, encrypted.

Optional columns:

• snmpinterfaces - this returns the list of interfaces associated with the host.
• snmptrap_tracing - this returns 1 if SNMP trap tracing is enabled for this host

Warning: If you change the list of servicechecks and do not specify the exception/timed_exception/remove_servicecheck parameters, this will default to undef, undef and 0 respectively.

Note: When applying a timed exception, if the related timeperiod is not found, the timed exception is silently dropped.

Note: The reference to the monitored_by related object is available from 3.11.0 onwards.

Note: For host attributes, if an arg is set to be encrypted for this particular attribute, the value will not exist in the GET request.

Notes: Errors will be thrown if validation fails for check_interval, retry_check_interval or check_attempts

It is possible to run a test service check to check if the arguments supplied to a plugin will work during the configuration of a host.

URL: /rest/config/host/testservicecheck

Method: GET or POST

Input URL parameters:

• scid - this is the service check id number. Required
• args - the arguments to test. Required. Note that some characters will throw an error: $( or any of ;|&\n<>[]{}\ - also an audit log entry will be created to log the error.
• monitored_by - the id of the monitoring server to run the test service check from. If not specified, will use the primary monitoring cluster.
• hostid - the id of the host, if applicable. Some passwords will be retrieved from the database if required.
• snmp_version - SNMP information
• snmp_port
• snmp_community
• snmpv3_username
• snmpv3_authpassword
• snmpv3_authprotocol
• snmpv3_privprotocol
• snmpv3_privpassword

Output:

A successful execution will return:

{
   "command" : "check_snmp_sysinfo -H '127.0.0.1' -t 5 -v '3' -U 'user3' -P XXauthpasswordXX -a \"md5\" -e 'des' -x XXprivpasswordXX",
   "monitored_by" : "master",
   "return_code" : "0",
   "stderr" : "",
   "stdout" : "Status is OK - SYSTEM: debian7 CONTACT: Joe Bloggs LOCATION: Reading, UK, IN SNMP AGENT: .1.3.6.1.4.1.8072.3.2.10 Linux debian7 3.2.0-4-686-pae #1 SMP Debian 3.2.57-3 i686\n"
}

Note that passwords will be cleansed of the actual value.

An audit log entry will be made on successful execution.

An error will return a status code of 400 with an error message.

Object type: hostcheckcommand

Example GET:

{
   "object" : {
      "priority" : "1",
      "plugin" : {
         "ref" : "/rest/config/plugin/check_icmp",
         "name" : "check_icmp"
      },
      "hosts" : [
         {
            "ref" : "/rest/config/host/14",
            "name" : "doesnt_exist_1"
         },
         {
            "ref" : "/rest/config/host/15",
            "name" : "doesnt_exist_2"
         },
         {
            "ref" : "/rest/config/host/16",
            "name" : "singlehostgroup"
         }
      ],
      "name" : "ping",
      "args" : "-H $HOSTADDRESS$ -t 3 -w 500.0,80% -c 1000.0,100%",
      "id" : "15",
      "uncommitted" : "0"
   }
}

Note: You cannot PUT the list of hosts. The reference to plugin is currently unavailable.

Object type: hostgroup

Example GET:

{
   "object" : {
      "hosts" : [],
      "parent" : {
            "name" : "Opsview",
            "matpath" : "Opsview,",
            "ref" : "/rest/config/hostgroup/1"
         },
      "name" : "Production",
      "id" : "2",
      "children" : [
         {
            "name" : "London",
            "ref": "/rest/config/hostgroup/7"
         },
         {
            "name" : "Paris",
            "ref": "/rest/config/hostgroup/3"
         },
         {
            "name" : "New York",
            "ref": "/rest/config/hostgroup/6"
         }
      ],
      "uncommitted" : "0",
      "matpath" : "Opsview,Production,",
      "is_leaf" : 0
   }
}

The matpath is a comma separated list of host groups that define this hostgroup's location in the topology.

The parent contains a the “matpath” attribute to uniquely identify the parent for a host group as it is possible to have duplicated names in the host group hierarchy (from Opsview 3.11.2+).

If you GET with a parameter of order=dependency, the host groups will be listed based on a traversal of the hierarchy, so the top host group will be first and then it will go down a branch until it comes back up again (from Opsview 3.11.2+).

Note: When PUTing, you cannot change the children - you can only change the topology by amending the parent. Also, the is_leaf and matpath field is calculated, so cannot be changed.

Warning: The name column in NOT unique in host groups. Opsview has additional logic so that if you use a name and it cannot be found, then it will search based on the matpath (but the matpath has a 255 character limit). Use the id field where possible as that is unique.

Object type: hosticons

Only GET is supported.

Example GET

Request URL:/rest/config/hosticons

Response:

{
  list => [
    {
      img_prefix => "/images/logos/3com",
      name => "LOGO - 3com",
      ref => "/rest/config/hosticons/LOGO - 3com",
    },
    {
      img_prefix => "/images/logos/apc",
      name => "LOGO - APC",
      ref => "/rest/config/hosticons/LOGO - APC",
    },
    {
      img_prefix => "/images/logos/apple",
      name => "LOGO - Apple",
      ref => "/rest/config/hosticons/LOGO - Apple",
    },
  ],
  summary => {
    allrows => 3,
    page => 1,
    rows => 3,
    totalpages => 1,
    totalrows => 3
  },
}

Object type: hosttemplate

Example GET:

{
   "object" : {
      "hosts" : [
         {
            "ref" : "/rest/config/host/7",
            "name" : "cisco"
         }
      ],
      "name" : "Cisco Mgt",
      "description" : "Cisco device Management URLs",
      "id" : "3",
      "has_icon" : 0,
      "servicechecks" : [
         {
            "ref" : "/rest/config/servicecheck/45",
            "name" : "Check Loadavg",
            "exception":"-w 5,5,5 -c 9,9,9",
            "timed_exception":null,
         },
         {
            "ref" : "/rest/config/servicecheck/4",
            "name" : "DNS",
            "exception":"--other --args",
            "timed_exception":null,
         },
         {
            "ref" : "/rest/config/servicecheck/6",
            "name" : "HTTP",
            "timed_exception":{
                "timeperiod" : { "name" : "workhours" },
                "args" : "--url=%URL% -w 15 -c 20",
            },
            "exception":null,
      ],
      "managementurls" : [
         {
            "url" : "ssh://$HOSTADDRESS$",
            "name" : "SSH",
            "id" : "4"
         },
         {
            "url" : "telnet://$HOSTADDRESS$",
            "name" : "Telnet",
            "id" : "5"
         }
      ],
      "uncommitted" : "1"
   }
}

Notes on attributes:

• remove_hostservicechecks - see the Host Templates configuration section for information about this attribute.
• has_icon - if set to 0, then there is no icon available. Otherwise will be set to epoch seconds as the time that the icon was updated. Icons can be found at /images/hticons/HTID/100×100.png, where HTID is the host template id number. There are also icons in 40×40.png and 20×20.png

Host Template - Upload

Host template is staged, parsed and checked for conflicts to see if an import would be successful.

Requires: ADMINACCESS.

URL: /rest/config/hosttemplate/upload

Method:

• POST - upload new opspack
• GET, PUT, DELETE - unimplemented

Headers:

• Content-Type must be set to a form upload format, as the file will be uploaded

Parameters:

• filename - file name to upload. Filename must not contain ".." or "/" or spaces

Will return status 200 unless there is an exceptional failure. Will log to audit log when submitted.

Returns for a failure with status 200:
{
success: false,
error: "Opspack contains ....", // If success is false, will return an internationalised string for display
}

Returns for a success:
{
success: true,
stdout: ['text from opspack','next line'], // Strings from the opspack test import process
exists: true, // Returns true if there is any conflict in the opspack for importing. Details in the stdout
}

Host Template - Import

Requires: ADMINACCESS.

Needs changelog if enabled.

URL: /rest/config/hosttemplate/import

Method:

• POST - import opspack
• GET, PUT, DELETE - unimplemented

Parameters:

• filename - opspack to import from the prior upload
• overwrite - default 0. If 1, force import of opspack
• changelog - required if changelog is enabled

Will log to audit log when submitted.

Returns:
{
success: true,
return_code: 0, // Return code from the opspack import process
stdout: [], // Array of strings from opspack import output
stderr: [], // Array of strings from opspack import errors
}

Example import script

This example script in perl, import_opspack_via_rest.pl, shows how to code the upload & import of an Opspack.

Host template - Export Opspack

Prepares an opspack for export. Take the generated filename for retrieving in a subsequent call.

Requires: ADMINACCESS.

URL: /rest/config/hosttemplate/ID/export

Method:

• POST - starts an opspack export
• DELETE, GET, PUT - unimplemented

Returns:
{
success: true,
filename: "FILENAME.opspack" // Will be a generated temporary name
}

Host template - Retrieve Opspack

Retrieves a previously exported opspack. When the file is downloaded, the file will be removed.

No specific access required.

URL: /rest/exportedFile

Method:

• GET - retrieves an exported opspack
• POST, PUT, DELETE - unimplemented

Parameters:

• filename - opspack to retrieve. Use the temporary filename from the Export Opspack call

Returns the contents of the file, with a content type of "application/octet-stream".

Example export process

$ opsview_rest --username=admin --password=initial --pretty --data-format=json POST "config/hosttemplate/1/export"
{
"filename" : "opsview-component-agent:tempcman1ESWWKpFnxx3.opspack",
"success" : true
}
$ wget --header="Accept: application/json" -O saved.opspack "http://localhost/rest/exportedFile?filename=opsview-component-agent:tempcman1ESWWKpFnxx3.opspack"

Host template is staged, parsed and checked for conflicts to see if an import would be successful.

Requires: ADMINACCESS.

URL: /rest/config/hosttemplate/upload

Method:

POST - upload new opspack
GET, PUT, DELETE - unimplemented
Headers:

Content-Type must be set to a form upload format, as the file will be uploaded
Parameters:

filename - file name to upload. Filename must not contain ".." or "/" or spaces
Will return status 200 unless there is an exceptional failure. Will log to audit log when submitted.

Returns for a failure with status 200:

{
  success: false,
  error: "Opspack contains ....", // If success is false, will return an internationalised string for display
}

Returns for a success:

{
 success: true,
 stdout: ['text from opspack','next line'], // Strings from the opspack test import process
 exists: true,                   // Returns true if there is any conflict in the opspack for importing. Details in the stdout
}

Requires: ADMINACCESS.

Needs changelog if enabled.

URL: /rest/config/hosttemplate/import

Method:

POST - import opspack
GET, PUT, DELETE - unimplemented
Parameters:

filename - opspack to import from the prior upload
overwrite - default 0. If 1, force import of opspack
changelog - required if changelog is enabled
Will log to audit log when submitted.

Returns:

{
 success: true,
 return_code: 0, // Return code from the opspack import process
 stdout: [],     // Array of strings from opspack import output
 stderr: [],     // Array of strings from opspack import errors
}

Example import script
This example script in perl, import_opspack_via_rest.pl, shows how to code the upload & import of an Opspack.

Prepares an opspack for export. Take the generated filename for retrieving in a subsequent call.

Requires: ADMINACCESS.

URL: /rest/config/hosttemplate/ID/export

Method:

POST - starts an opspack export
DELETE - unimplemented
Returns:

{
 success: true,
 filename: "FILENAME.opspack"  // Will be a generated temporary name
}

Retrieves a previously exported opspack. When the file is downloaded, the file will be removed.

No specific access required.

URL: /rest/exportedFile

Method:

GET - retrieves an exported opspack
POST, PUT, DELETE - unimplemented
Parameters:

filename - opspack to retrieve. Use the temporary filename from the Export Opspack call
Returns the contents of the file, with a content type of "application/octet-stream".

Example export process

$ opsview_rest --username=admin --password=initial --pretty --data-format=json POST "config/hosttemplate/1/export"
{
   "filename" : "opsview-component-agent:tempcman1ESWWKpFnxx3.opspack",
   "success" : true
}

$ wget --header="Accept: application/json" -O saved.opspack "http://localhost/rest/exportedFile?filename=opsview-component-agent:tempcman1ESWWKpFnxx3.opspack"

Object type: keyword

Note: even though they are called hashtags in the UI and documentation, they are still referenced as keywords in the Rest API

URL: /rest/config/keyword

Parameters:

• calculate_hard_states - if set, the hashtag summary status will be based on the hard states of the services, not the current state. Note, it will be possible that the hashtag will have a calculated state of OK but in an unhandled state

Example GET:

{
   "object" : {
      "all_hosts" : "0",
      "hosts" : [
         {
            "ref" : "/rest/config/host/7",
            "name" : "cisco"
         },
         {
            "ref" : "/rest/config/host/8",
            "name" : "cisco1"
         }
      ],
      "roles" : [
         {
            "ref" : "/rest/config/role/14",
            "name" : "View some, change none"
         },
         {
            "ref" : "/rest/config/role/15",
            "name" : "View some, change none, no notify"
         }
      ],
      "all_servicechecks" : "0",
      "style" : "group_by_host",
      "name" : "cisco",
      "description" : "cisco devices",
      "servicechecks" : [
         {
            "ref" : "/rest/config/servicecheck/82",
            "name" : "Another exception"
         },
         {
            "ref" : "/rest/config/servicecheck/81",
            "name" : "Test exceptions"
         }
      ],
      "id" : "2",
      "enabled" : "1",
      "uncommitted" : "1"
   }
}

Object type: monitoringcluster

URL: /rest/config/monitoringcluster

Example GET:

{
   "object" : {
      "roles" : [
         {
            "ref" : "/rest/config/role/12",
            "name" : "View some, change some"
         }
      ],
      "activated" : "1",
      "monitors" : [
         {
            "ref" : "/rest/config/host/10",
            "name" : "cisco3"
         },
         {
            "ref" : "/rest/config/host/4",
            "name" : "monitored_remotely"
         }
      ],
      "name" : "ClusterA",
      "nodes" : [
         {
            "host" : {
               "ip" : "192.168.10.20",
               "ref" : "/rest/config/host/5",
               "name" : "collector1"
            },
            "slave_port" : "22"   // Unused in 6.0
         }
      ],
      "id" : "2",
      "uncommitted" : "1"
   }
}

If id=1, this is the primary monitoring cluster.

DELETEs are blocked if the monitoring cluster is the primary, or if there are any hosts still monitored by this monitoring cluster.

Additional parameters:

• order - can be num_hosts or num_nodes to order the list of monitoring clusters by those columns
• include_delete_info - if set, will return extra fields indicating if a monitoring cluster is not deletable because it is the primary, it is used as a netflow collector, it still has hosts associated to it, or if the monitoring cluster is license locked

There is an activated_calculated column that will be included if order=activated_calculated is set. This can be one of 4 values (note that value 3 is not ordered correctly - this is a known limitation):

• 0 = Not activated
• 1 = Activated cluster
• 2 = Always activated (primary)
• 3 = Disabled due to licensing

When PUT/POSTing to monitoringclusters, monitors and roles is unsupported. The nodes parameter should be of the form:

nodes: [ { id: 13 }, { id: 20 } ]

where the ids are the host ids of the collectors. For the primary monitoring cluster, only the first node is used and the remainder silently ignored.

Object type: netflow_collector

Example GET all

Request URL:/rest/config/netflow_collector

Response:
{
"list" : [
{
"id" : "1",
"monitoring_server" : {
"name" : "Master Monitoring Server",
"ref" : "/rest/config/monitoringcluster/1"
},
"name" : "Master server collector",
"port": "9995",
"ref" : "/rest/config/netflowcollector/1",
"sport": "6343",
"uncommitted" : "0"
},
{
"id" : "2",
"monitoring_server" : {
"name" : "Boston Datacentre",
"ref" : "/rest/config/monitoringcluster/2"
},
"name" : "Boston collector",
"port": "9995",
"ref" : "/rest/config/netflowcollector/2",
"sport": "6343",
"uncommitted" : "0"
}
],
"summary" : {
"allrows" : "2",
"page" : "1",
"rows" : "2",
"totalpages" : "1",
"totalrows" : "2"
}
}

Example GET single

Request URL:/rest/config/netflow_collector/1

Response:
{
"object" : {
"id" : "1",
"monitoring_server" : {
"name" : "Master Monitoring Server",
"ref" : "/rest/config/monitoringcluster/1"
},
"port": "9995",
"name" : "Master server collector",
"sport": "6343",
"uncommitted" : "0"
}
}

Example PUT

Note: Only the name can be updated for an existing collector.

Request URL:/rest/config/netflow_collector/1

Request data:
{
"id" : "1",
"monitoringserver_id" : "1", // Ignored
"name" : "A new name",
"port": "9995",
"sport": "6343",
}

Response:
{
"object" : {
"id" : "1",
"monitoring_server" : {
"name" : "Master Monitoring Server",
"ref" : "/rest/config/monitoringcluster/1"
},
"port": "9995",
"name" : "A new name",
"sport": "6343",
"uncommitted" : "1"
}
}

Example POST

Request URL:/rest/config/netflow_collector

Request data:
{
"monitoringserver_id" : "2",
"name" : "Second collector",
}

Response:
{
"object" : {
"id" : "3",
"monitoring_server" : {
"name" : "Boston Datacentre",
"ref" : "/rest/config/monitoringcluster/2"
},
"port": "9995",
"name" : "Second collector",
"sport": "6343",
"uncommitted" : "1"
}
}

Example DELETE

Request URL:/rest/config/netflow_collector/2

Response:
{
"success" : "1"
}

Object type: netflow_source

Example GET all

Request URL:/rest/config/netflow_source

Response:

{
   "list" : [
      {
         "active" : "0",
         "collector_id" : "1",
         "host_id" : "7",
         "id" : "1",
         "port" : "5454",
         "ref" : "/rest/config/netflowsource/1",
         "uncommitted" : "0"
      },
      {
         "active" : "1",
         "collector_id" : "1",
         "host_id" : "9",
         "id" : "3",
         "port" : "5455",
         "ref" : "/rest/config/netflowsource/3",
         "uncommitted" : "0"
      },
      {
         "active" : "1",
         "collector_id" : "2",
         "host_id" : "11",
         "id" : "5",
         "port" : "5454",
         "ref" : "/rest/config/netflowsource/5",
         "uncommitted" : "0"
      },
      {
         "active" : "1",
         "collector_id" : "1",
         "host_id" : "13",
         "id" : "9",
         "port" : "123",
         "ref" : "/rest/config/netflowsource/9",
         "uncommitted" : "0"
      }
   ],
   "summary" : {
      "allrows" : "4",
      "page" : "1",
      "rows" : "4",
      "totalpages" : "1",
      "totalrows" : "4"
   }
}

Example GET single

Request URL:/rest/config/netflow_source/5

Response:

{
   "object" : {
      "active" : "1",
      "collector_id" : "2",
      "host_id" : "11",
      "id" : "5",
      "port" : "5454",
      "uncommitted" : "0"
   }
}

Example PUT

NOTE: Only the active state (boolean) can be changed for an existing source.

Request URL:/rest/config/netflow_source/1

Request data:

{
   "object" : {
      "active" : "1",
      "collector_id" : "1",
      "host_id" : "7",
      "port" : "5454",
   }
}

Response:

{
   "object" : {
      "active" : "1",
      "collector_id" : "1",
      "host_id" : "7",
      "id" : "1",
      "port" : "5454",
      "uncommitted" : "1"
   }
}

Example POST

Request URL:/rest/config/netflow_source

Request data:

{
   "object" : {
      "active" : "1",
      "collector_id" : "2",
      "host_id" : "12",
      "port" : "1234",
   }
}

Response:

{
   "object" : {
      "active" : "1",
      "collector_id" : "2",
      "host_id" : "12",
      "id" : "10",
      "port" : "1234",
      "uncommitted" : "1"
   }
}

Example DELETE

Request URL:/rest/config/netflow_source/5

Response:

{
   "success" : "1"
}

Object type: notificationmethod

Example GET:

{
   "object" : {
      "namespace" : "com.opsview.notificationmethods.aql",
      "master" : "0",
      "name" : "AQL",
      "active" : "1",
      "notificationprofiles" : [
         {
            "ref" : "/rest/config/notificationprofile/12",
            "name" : "Non work hours sms"
         },
         {
            "ref" : "/rest/config/notificationprofile/3",
            "name" : "Default"
         }
      ],
      "id" : "1",
      "uncommitted" : "0",
      "command" : "submit_sms_aql -u '' -p '' -P ''",
      "contact_variables" : "PAGER",
      "variables" : [
        {
           "name" : "AQL_PASSWORD",
           "value" : "aqlpass"
        },
        {
           "name" : "AQL_PROXY_SERVER",
           "value" : "http://proxy.example.com"
        },
        {
           "name" : "AQL_USERNAME",
           "value" : "aqluser"
        }
     ]
   }
}

Optional parameters:

• include_contacts - if set to 1, will return a list of contacts for all the notification profiles and the shared notification profiles as an array of hashes, eg:

    notificationprofile_contacts => [
     { id => 8, name => "viewsomechangenone" },
     { id => 9, name => "viewsomechangenonewonotify" },
   ]
  

Object type: role

Example role:

{
   "object" : {
      "contacts" : [
         {
            "ref" : "/rest/config/contact/1",
            "name" : "admin"
         }
      ],
      "monitoringservers" : [],
      "hostgroups" : [
         {
            "ref" : "/rest/config/hostgroup/1",
            "name" : "Opsview"
         }
      ],
      "name" : "Admin",
      "id" : "10",
      "description" : "quot;Administrator access",
      "accesses" : [
         {
            "ref" : "/rest/config/access/1",
            "name" : "VIEWALL"
         },
         {
            "ref" : "/rest/config/access/14",
            "name" : "PASSWORDSAVE"
         }
      ],
      "access_hostgroups": [],
      "access_servicegroups": [],
      "access_keywords" : [],
      "all_hostgroups" : "0",
      "all_servicegroups" : "0",
      "all_keywords" : "0",
      "all_monitoringservers" : "1",
      "uncommitted" : "0"
   }
}

If you add a parameter of “order=priority”, this will list the roles in the same order that the web page displays it. Without this parameter, the order is undefined, though usually by id.

Note: The reference to access is not currently available.

Note: From Opsview 3.11.0, the fields access_hostgroups, access_servicegroups, access_keywords, all_hostgroups, all_servicegroups and all_keywords are available, as this data is moved from the contact level.

Object type: servicecheck

Example GET:

{
   "object" : {
      "alert_from_failure" : "5",
      "args" : "",
      "attribute" : null,
      "calculate_rate" : "no",
      "cascaded_from" : {
         "name" : "Interface Poller",
         "ref" : "/rest/config/servicecheck/107"
      },
      "check_attempts" : "5",
      "check_freshness" : "1",
      "check_interval" : "25",
      "check_period" : {
         "name" : "workhours",
         "ref" : "/rest/config/timeperiod/2"
      },
      "checktype" : {
         "name" : "SNMP trap",
         "ref" : "/rest/config/checktype/4"
      },
      "critical_comparison" : null,
      "critical_value" : null,
      "dependencies" : [
         {
            "name" : "Check Swap",
            "ref" : "/rest/config/servicecheck/46"
         },
         {
            "name" : "DHCP",
            "ref" : "/rest/config/servicecheck/3"
         }
      ],
      "description" : "",
      "event_handler" : "",
      "flap_detection_enabled" : "1",
      "freshness_type" : "set_stale",
      "hosts" : [
         {
            "name" : "cisco4",
            "ref" : "/rest/config/host/11"
         },
         {
            "name" : "opsview",
            "ref" : "/rest/config/host/1"
         }
      ],
      "hosttemplates" : [
         {
            "name" : "Network - Base",
            "ref" : "/rest/config/hosttemplate/2"
         }
      ],
      "id" : "79",
      "invertresults" : "0",
      "keywords" : [
         {
            "name" : "cisco",
            "ref" : "/rest/config/keyword/2"
         },
         {
            "name" : "cisco_gp2",
            "ref" : "/rest/config/keyword/4"
         }
      ],
      "label" : null,
      "markdown_filter" : "0",
      "name" : "Coldstart",
      "notification_interval" : null,
      "notification_options" : "w,c,r,u",
      "notification_period" : null,
      "oid" : null,
      "plugin" : null,
      "retry_check_interval" : null,
      "sensitive_arguments" : "1",
      "servicegroup" : {
         "name" : "Operations",
         "ref" : "/rest/config/servicegroup/1"
      },
      "snmptraprules" : [
         {
            "alertlevel" : "1",
            "code" : "\"${TRAPNAME}\" =~ /SNMPv2-MIB::coldstart/i",
            "message" : "Device coldstarted",
            "name" : "Check coldstart",
            "process" : "1",
            "ref" : "/rest/config/snmptraprule/1",
            "uncommitted" : "1"
         },
         {
            "alertlevel" : "0",
            "code" : "1",
            "message" : "OK",
            "name" : "Otherwise Ok",
            "process" : "1",
            "ref" : "/rest/config/snmptraprule/2",
            "uncommitted" : "1"
         }
      ],
      "stale_state" : "2",
      "stale_text" : "Set to critical!!",
      "stale_threshold_seconds" : "3750",
      "stalking" : null,
      "uncommitted" : "1",
      "volatile" : "0",
      "warning_comparison" : null,
      "warning_value" : null
   }
}

If you set a parameter of order with the value dependency, the service checks will be listed based on their level, which means that if there are service check dependencies, the most dependent items will be listed first.

Note: The reference to plugin, checktype and snmptraprule is not available.

Note: Errors will be thrown if validation fails for check_interval, retry_check_interval, check_attempts or stale_threshold_seconds

Notes: checktype must be specified at service check creation time. This field cannot be subsequently changed. Cloning will not allow a change in checktype

NOtes: For checktype = 1 (active) or 5 (SNMP polling), the fields for check_interval, retry_check_interval and check_attempts will be returned in the REST API, otherwise they will not. Similarly, these fields will be processed on input, otherwise they are ignored

Object type: servicegroup

Example GET:

{
   "object" : {
      "name" : "Application - web server",
      "id" : "2",
      "servicechecks" : [
         {
            "ref" : "/rest/config/servicecheck/85",
            "name" : "HTTP"
         },
      ],
      "uncommitted" : "0"
  }
}

Note: When PUTing, you cannot change the related service checks. If you want to change those, you have to change the related service check itself.

Object type: sharednotificationprofile

Example GET:

{
   "object" : {
      "all_hostgroups" : "1",
      "all_keywords" : "1",
      "all_servicegroups" : "1",
      "host_notification_options" : "u,d,r,f",
      "hostgroups" : [],
      "id" : "3",
      "keywords" : [],
      "name" : "demorole profile 1",
      "notification_level" : "1",
      "notification_period" : {
         "name" : "24x7",
         "ref" : "/rest/config/timeperiod/1"
      },
      "notificationmethods" : [],
      "role" : {
         "name" : "demorole",
         "ref" : "/rest/config/role/17"
      },
      "service_notification_options" : "w,c,r,u,f",
      "servicegroups" : [],
      "uncommitted" : "0"
   {
{

Object type: tenancy

Example GET all

Request URL:/rest/config/tenancy

Response:

{
   "list" : [
      {
         "description" : "Foo description",
         "id" : "1",
         "name" : "Foo name",
         "primary_role" : {
            "name" : "View all, change none",
            "ref" : "/rest/config/role/13"
         },
         "priority" : "0",
         "ref" : "/rest/config/tenancy/1"
      },
      {
         "description" : "Bar description",
         "id" : "2",
         "name" : "Bar name",
         "primary_role" : {
            "name" : "View all, change none",
            "ref" : "/rest/config/role/13"
         },
         "priority" : "0",
         "ref" : "/rest/config/tenancy/2"
      }
   ],
   "summary" : {
      "allrows" : "2",
      "page" : "1",
      "rows" : "2",
      "totalpages" : "1",
      "totalrows" : "2"
   }
}

Example GET single

Request URL:/rest/config/tenancy/1

Response:

{
   "object" : {
      "description" : "Foo description",
      "id" : "1",
      "name" : "Foo name",
      "primary_role" : {
         "name" : "View all, change none",
         "ref" : "/rest/config/role/13"
      },
      "priority" : "0"
   }
}

Example PUT

Request URL:/rest/config/tenancy/1

Request data:

{
   "object" : {
      "description" : "The description of Foo",
      "name" : "The name of Foo",
      "primary_role" : {
         "name" : "Admin no configurehosts"
      },
      "priority" : "1"
   }
}

Response:

{
   "object" : {
      "description" : "The description of Foo",
      "id" : "1",
      "name" : "The name of Foo",
      "primary_role" : {
         "name" : "Admin no configurehosts",
         "ref" : "/rest/config/role/16"
      },
      "priority" : "1"
   }
}

Example POST

Request URL:/rest/config/tenancy

Request data:

{
   "object" : {
      "description" : "Foo description",
      "name" : "Foo name",
      "primary_role" : {
         "name" : "View all, change none"
      },
      "priority" : "0"
   }
}

Response:

{
   "object" : {
      "description" : "Foo description",
      "id" : "1",
      "name" : "Foo name",
      "primary_role" : {
         "name" : "View all, change none",
         "ref" : "/rest/config/role/13"
      },
      "priority" : "0"
   }
}

Example DELETE

Request URL:/rest/config/tenancy/2

Response:

{
   "success" : "1"
}

Object type: timeperiod

Example GET:

{
   "object" : {
      "sunday" : "00:00-24:00",
      "friday" : "00:00-09:00,17:00-24:00",
      "name" : "nonworkhours",
      "servicecheck_notification_periods" : [
         {
            "ref" : "/rest/config/servicecheck/26",
            "name" : "TFTP"
         },
         {
            "ref" : "/rest/config/servicecheck/43",
            "name" : "Whois"
         }
      ],
      "servicecheck_check_periods" : [
         {
            "ref" : "/rest/config/servicecheck/43",
            "name" : "Whois"
         }
      ],
      "monday" : "00:00-09:00,17:00-24:00",
      "tuesday" : "00:00-09:00,17:00-24:00",
      "saturday" : "00:00-24:00",
      "wednesday" : "00:00-09:00,17:00-24:00",
      "thursday" : "00:00-09:00,17:00-24:00",
      "id" : "3",
      "host_check_periods" : [
         {
            "ref" : "/rest/config/host/22",
            "name" : "monitored_by_cluster"
         },
         {
            "ref" : "/rest/config/host/4",
            "name" : "monitored_by_collector"
         }
      ],
      "alias" : "Non-work Hours",
      "host_notification_periods" : [
         {
            "ref" : "/rest/config/host/12",
            "name" : "toclone"
         }
      ],
      "uncommitted" : "0"
   }
}

Note: When PUTing, you cannot change the related host/service check period/notification periods. If you want to change those, you have to change the related host/service check itself.

Object type: plugin
URL: /rest/config/plugin

Methods:

• GET - returns a list of the plugins
• POST, PUT, DELETE - unimplemented

Parameters:

• order - Use "num_servicechecks" to return the list ordered by servicechecks used
• s.name - filter by name column. Use % to add wildcards

Example GET /rest/config/plugin:

{
   "list" : [
      {
         "envvars" : "",
         "name" : "check_nrpe",
         "servicechecks" : [
            {
               "name" : "/",
               "ref" : "/rest/config/servicecheck/47"
            },
            ....
            {
               "name" : "Z Drive",
               "ref" : "/rest/config/servicecheck/71"
            }
         ]
      },
      {
         "envvars" : "",
         "name" : "check_tcp",
         "servicechecks" : [
            {
               "name" : "AFS",
               "ref" : "/rest/config/servicecheck/1"
            },
            ....
            {
               "name" : "X.400",
               "ref" : "/rest/config/servicecheck/32"
            }
         ]
      },
      {
         "envvars" : "",
         "name" : "check_snmp_linkstatus",
         "servicechecks" : [
            {
               "name" : "Discards",
               "ref" : "/rest/config/servicecheck/101"
            },
            {
               "name" : "Errors",
               "ref" : "/rest/config/servicecheck/100"
            },
            {
               "name" : "Interface",
               "ref" : "/rest/config/servicecheck/95"
            }
         ]
      }
   ],
   "summary" : {
      "allrows" : "125",
      "page" : "1",
      "rows" : "3",
      "totalpages" : "42",
      "totalrows" : "125"
   }
}

URL: /rest/config/plugin/PLUGINNAME

Methods:

• DELETE - Deletes this plugin from the database and removes from the list of plugins in the master server
• GET, POST, PUT - unimplemented

Note: if you have the plugin on a remote collector, this will not be removed.

Plugin - Upload

• ADMINACCESS only. Plugin is staged and executed to test if the plugin is appropriate.

URL: /rest/config/plugin/upload
Method:

• POST - upload new plugin

When uploading:

• Audit log to say uploading a plugin. Log errors to opsview-web.log
• check if plugin already exists
• execute plugin with -h. Returns return_code, stderr and stdout

Parameters:

• filename - file name to upload. File must begin with "check_". Filename must not contain ".." or "/" or spaces
• changelog - if Change Log is enabled, this must be set with a message

Returns for a failure:

{
 success: false,                 // or true
 error: "Plugin already exists", // If success is false, will return an internationalised string for display
 detail: "File not found",       // May exist if success is false. Will have further information about failure
}

Returns for a success:

{
 return_code: 0,                                          // Return code of script
 stdout: 'text from plugin running -h\nwith extra lines', // Output from plugin
 stderr: '',                                              // Stderr from plugin
 exists: true,                                            // Returns true if a plugin of the same name is already live
 valid_plugin: true,                                      // This is a valid plugin based on heuristics. Could return false
}

Plugin - Import

• Needs ADMINACCESS. Needs changelog. Check plugin again.

URL: /rest/config/plugin/import

Method:

• POST - make new plugin live
• Audit log when submitted. Log errors to opsview-web.log.
• Removes plugin from staging area and copies to live.

Parameters:

• filename - plugin to migrate from staging to live
• overwrite - default 0. If 1, allow overwriting of plugin
• changelog - required if changelog is enabled

Returns:

{ success: true }

URL: /rest/downtime.

• 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

Requires DOWNTIMESOME access.

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

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.

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.

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 host or service objects. 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 Opsview as downtime for each host and its services.
You can choose hosts or services using the same URL parameters as the status API, with the following 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.

• hostgroups (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)

• hosts:

  • 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)

• services:

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

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.

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.

Listing Downtimes

Output of a list response:

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

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

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.

Attributes required for creating a downtimes:

• 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:

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

If the same parameters is 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 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>"'

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

Security level required:

• VIEWALL - can see all objects
• VIEWSOME - filtered by the user's access to objects

URL: /rest/status/hostgroup

• GET - lists summarised information about host groups
• PUT, POST, DELETE - unimplemented

URL parameters:

• hostgroupid - includes this host group in list. Can be repeated. Note, this is for this one host group id only.
• parentid - includes all host groups with this parent. Can be repeated.
• fromhostgroupid - will include all host groups from this point in the hierarchy “downwards”. Includes itself. Can be repeated.
• has_perfdata - if set, will only return service that have performance data. Default not set.
• host - filter hosts by this host name. Can be repeated.
• servicecheck - filter services by this service check name. Can be repeated.
• filter - either handled or unhandled. Filters services by this condition.
• host_filter - either handled or unhandled. Filters host by this condition.
• state - filters by services in this state. Expects the numeric id for state. Can be repeated.
• host_state - filters by hosts in this state. Expects the numeric id for state. Can be repeated.
• includeunhandledhosts - if set to 1, will include hosts that are unhandled. Otherwise will only return services that are unhandled.
• include_servicegroups - if set to 1, will include service group information, with number of ok, warning, critical and unknown states.
• only_leaves - if set to 1, will only return host groups that are leaf host groups.
• rows - returns this number of rows. Set to all to get all results. Defaults to all.
• page - returns this page number if rows is set to a number. Defaults to 1st page.
• cols - can specify columns to remove. Possible columns: leaf, matpath. Example: cols=-leaf,-matpath.
• order - if set to dependency, will return order based on hierarchy, starting with the top first then depth first. Otherwise, returns back ordered by name.

NOTE: When using fromhostgroupid, previous versions of Opsview were counting hosts and services multiple times in the summary - from 6.0, this will be the correct total number.

Example output:

{
   "summary" : {
      "handled" : "27",
      "unhandled" : "37",
      "service" : {
         "ok" : "4",
         "critical" : "3",
         "handled" : "10",
         "unhandled" : "35",
         "unknown" : "38",
         "total" : "45"
      },
      "total" : "64",
      "totalhgs" : "4",
      "host" : {
         "handled" : "17",
         "unhandled" : "2",
         "up" : "15",
         "down" : "4",
         "total" : "19"
      }
   },
   "list" : [
      {
         "hosts" : {
            "handled" : "7",
            "unhandled" : "1",
            "up" : {
               "handled" : "6"
            },
            "down" : {
               "handled" : "1",
               "unhandled" : "1"
            },
            "total" : "8"
         },
         "hostgroupid" : "4",
         "services" : {
            "ok" : {
               "handled" : "1"
            },
            "handled" : "4",
            "computed_state" : "unknown",
            "unhandled" : "15",
            "unknown" : {
               "handled" : "3",
               "unhandled" : "15"
            },
            "total" : "19"
         },
         "matpath" : [
            {
               "name" : "Opsview",
               "id" : "1"
            },
            {
               "name" : "UK",
               "id" : "3"
            }
         ],
         "computed_state" : "critical",
         "downtime" : "2",
         "name" : "Leaf",
         "leaf" : "0"
      },
      {
         "hosts" : {
            "handled" : "10",
            "unhandled" : "1",
            "up" : {
               "handled" : "9"
            },
            "down" : {
               "handled" : "1",
               "unhandled" : "1"
            },
            "total" : "11"
         },
         "hostgroupid" : "1",
         "services" : {
            "ok" : {
               "handled" : "3"
            },
            "critical" : {
               "unhandled" : "3"
            },
            "handled" : "6",
            "computed_state" : "critical",
            "unhandled" : "20",
            "unknown" : {
               "handled" : "3",
               "unhandled" : "17"
            },
            "total" : "26"
         },
         "computed_state" : "critical",
         "matpath" : [],
         "downtime" : "2",
         "name" : "Opsview",
         "leaf" : "0"
      }
   ]
}

Note: The computed_state keyword represents the highest state based on host state and service state. Specifically, this will return critical if the host is down or unreachable otherwise the service computed_state. This is available from Opsview 3.13.0.
The summary.totalhgs value represents the number of host groups in this request, without any filtering. This means that if the value is > 0, the user has access to see host groups from this part of the host group tree. If the value is 0, then the user does not have access to this part of the host group tree.

URL: /rest/status/host

• GET - lists summarised information about hosts.
• PUT, POST, DELETE - unimplemented.

URL parameters:

• hostgroupid - includes this host group in list. Can be repeated. Note, this will return all hosts in this hosgroupid and below in the hierarchy (so a hostgroupid of 1 effectively returns all hosts).
• host - filter hosts by this host name. Can be repeated.
• servicecheck - filter services by this service check name. Can be repeated.
• filter - either handled or unhandled. Filters services by this condition.
• host_filter - either handled or unhandled. Filters host by this condition.
• state - filters by services in this state. Expects the numeric ID for state. Can be repeated.
• state_type - filters by service state type. Expects either 0 (soft) or 1 (hard). Defaults to both.
• host_state - filters by hosts in this state. Expects the numeric ID for state. Can be repeated.
• host_state_type - filters by host state type. Expects either 0 (soft) or 1 (hard). Defaults to both.
• includeextradetails - if set, will include extra detail.
• rows - returns this number of rows. Set to all to get all results. Defaults to all.
• page - returns this page number if rows is set to a number. Defaults to 1st page.
• include_reload_time - If set to 1, then the summary data will include the last reload time of Opsview in epoch seconds.
• only_with_children - if set, then only hosts with at least 1 child are returned.
• monitoredby - if set, filter hosts if it is monitored by the monitoring server by this id.
• has_perfdata - if set, will only return service that have performance data. Default not set.

Example output for /rest/status/host?host=opcollector&host=opsview:

{
   "list" : [
      {
         "alias" : "Collector",
         "current_check_attempt" : "0",
         "downtime" : "0",
         "icon" : "opsview",
         "last_check" : "0",
         "max_check_attempts" : "0",
         "name" : "opcollector",
         "num_interfaces" : "0",
         "num_services" : "6",
         "output" : "Dummy output",
         "state" : "up",
         "state_duration" : 12345,
         "state_type" : "soft",
         "summary" : {
            "critical" : {
               "unhandled" : "1"
            },
            "handled" : "1",
            "ok" : {
               "handled" : "1"
            },
            "total" : "2",
            "unhandled" : "1"
         },
         "unhandled" : "0"
      },
      {
         "alias" : "Opsview Master Server",
         "comments" : "1",
         "current_check_attempt" : "0",
         "downtime" : "0",
         "icon" : "opsview",
         "last_check" : "0",
         "max_check_attempts"  : "0",
         "name" : "opsview",
         "num_interfaces" : "0",
         "num_services" : "6",
         "output" : "Dummy output",
         "state" : "up",
         "state_duration" : 12345,
         "state_type" : "soft",
         "summary" : {
            "critical" : {
               "unhandled" : "1"
            },
            "handled" : "1",
            "ok" : {
               "handled" : "1"
            },
            "total" : "2",
            "unhandled" : "1"
         },
         "unhandled" : "0"
      }
   ],
   "summary" : {
      "handled" : "4",
      "host" : {
         "handled" : "2",
         "total" : "2",
         "unhandled" : "0",
         "up" : "2"
      },
      "service" : {
         "critical" : "2",
         "handled" : "2",
         "ok" : "2",
         "total" : "4",
         "unhandled" : "2"
      },
      "total" : "6",
      "unhandled" : "2",
      "last_reload_time" : "1234567890",
   }
}

Note: The following attributes will only be returned if true. If the attribute does not exist, you can assume that the values are 0:

• acknowledged = 1
• flapping = 1

URL: /rest/status/service

• GET - lists information about services
• PUT, POST, DELETE - unimplemented

The URL parameters includes the service object filtering parameters. These are also available:

• downtime_start_time & downtime_comment - filter based on downtime that matches these conditions.
• filter - either handled or unhandled. Filters services by this condition.
• host_filter - either handled or unhandled. Filters host by this condition.
• state - filters by services in this state. Expects the numeric ID for state. Can be repeated.
• state_type - filters by service state type. Expects either 0 (soft) or 1 (hard). Defaults to both.
• host_state - filters by hosts in this state. Expects the numeric ID for state. Can be repeated. If includehosts=0, then the host state of each service must be in this state (this is an AND condition). If includehosts=1, then either services are in the chosen state or any host are in this chosen state (an OR condition)
• host_state_type - filters by host state type. Expects either 0 (soft) or 1 (hard). Defaults to both.
• includeperfdata - if set, will add data re: the performance metrics for services that have performance information.
• convertuom - if set, will convert performance data into base units. Eg, if value=1500 and uom=MB, with this flag set, will return value=1500000000 uom=bytes.
• includehandleddetails - if set, will include acknowledgement information.
• includehosts - this affects how state_type and host_state_type are processed. If includehosts=1, then state_type and host_state_type are in an OR condition, so hosts with that state type or services with that state type will be displayed. If includehosts=0, then the state_type for the service AND the host_state_type for the host must match
• type - only applicable when includehosts=1. This can be set to either 'host' or 'service'. If not set, will assume both. If set more than once, the first value is used
• rows - returns this number of rows. Set to all to get all results. Defaults to all.
• page - returns this page number if rows is set to a number. Defaults to 1st page.
• include_allrows - if set and page is set, this will return summary.allrows which will be the total number of rows based on the filtering parameters. Default no.
• recheck=1 - the response will filter only the objects that can be rechecked (default: 0)
• order - can order the results. Can be repeated. Valid values (you can suffix with _desc to order descending):
  • state - orders by service state.
    • If includehosts=0, host states have priority (DOWN, UNREACHABLE, UP, CRITICAL, WARNING, UKNOWN, OK)
    • If includehosts=1, then states are intermingled by priority (so DOWN, CRITICAL, WARNING, UNREACHABLE, UNKNOWN, UP, OK)
  • service - orders by service name
  • host - orders by host name
  • host_state - orders by host state
  • last_check - orders by last check time
  • last_state_change - orders by last state change time
  • state_duration - orders by most recent state changes first

Example output:

{
   "list" : [
      {
         "alias" : "Opsview Master Server",
         "comments" : "1",
         "current_check_attempt" : "0",
         "downtime" : "0",
         "icon" : "opsview",
         "last_check" : "1970-01-01 00:00:00",
         "max_check_attempts" : "0",
         "name" : "opsview",
         "num_interfaces" : "0",
         "num_services" : "6",
         "output" : "Dummy output",
         "services" : [
            {
               "current_check_attempt" : "1",
               "downtime" : "0",
               "last_check" : "2011-01-16 22:51:29",
               "markdown" : "0",
               "max_check_attempts" : "3",
               "name" : "Collector-node: opcollector",
               "output" : "collector-node check with fake results",
               "perfdata_available" : "1",
               "service_object_id" : "219",
               "state" : "ok",
               "state_type" : "hard",
               "state_duration" : "9296782",
               "unhandled" : "0"
            },
            {
               "current_check_attempt" : "1",
               "downtime" : "0",
               "last_check" : "2011-01-16 22:52:34",
               "markdown" : "0",
               "max_check_attempts" : "3",
               "name" : "Collector-node: opcollectorclusterA",
               "output" : "collector-node opcollectorclusterA check with fake results",
               "perfdata_available" : "1",
               "service_object_id" : "220",
               "state" : "critical",
               "state_type" : "soft",
               "state_duration" : "9296717",
               "unhandled" : "1"
            }
         ],
         "state" : "up",
         "state_type" : "hard",
         "state_duration" : "1304515071",
         "summary" : {
            "critical" : "1",
            "handled" : "1",
            "computed_state" : "critical",
            "ok" : "1",
            "total" : "2",
            "unhandled" : "1"
         },
         "unhandled" : "0"
      }
   ],
   "summary" : {
      "handled" : "2",
      "host" : {
         "handled" : "1",
         "total" : "1",
         "unhandled" : "0",
         "up" : "1"
      },
      "service" : {
         "critical" : "1",
         "handled" : "1",
         "ok" : "1",
         "total" : "2",
         "unhandled" : "1"
      },
      "total" : "3",
      "unhandled" : "1"
   }
}

Note: The following attributes will only be returned if true for a host or service. If the attribute does not exist, you can assume that the values are 0:

• acknowledged = 1
• flapping = 1

Note: The format of the last_check field has changed to being epoch seconds. To have the old behaviour, use the URL parameter of format_datetime=1.

There are common filtering parameters that can be used for filtering of service objects.
URL parameters:

• hostgroupid - includes this host group in list and all hosts and services below. Can be repeated.
• hostgroupname - includes this host group in list and all hosts and services below. Can be repeated. If a host group name is duplicated, all host groups will be considered.
• hostname - filter hosts by this host name. Can be repeated. Can include the % parameter for wildcard matching - use %25 in the URL so it doesn't get escaped. The parameter host is considered the same, but hostname will be used in preference.
• hostid - filter hosts by this host id. Can be repeated.
• servicename - filter services by this service check name. Can be repeated. Can include the % character for wildcard matching - use %25 in the URL so it doesn't get escaped. The parameter servicecheck is considered the same, but servicename will be used in preference.
• serviceid - filter services by this service id. Can be repeated.
• hs - filter services that match this format: hostname::servicename. Must match exactly. Can be repeated.
• keyword - filter services by keyword. Can be repeated.
• monitoredby - filter by name of the monitored by server. Can be repeated.
• has_perfdata - if set, will filter services that have performance data.
• can_change - if set, will only list services that the user can either change or set downtime for.
• htid - host template ID. Can be repeated.
• bsid - business service ID. Can be repeated.
• bcid - business component ID. Can be repeated.

URL: /rest/status

• POST - submits the new status of services
• GET, POST, DELETE - unimplemented

Filter parameters are noted above in Filtering Service Objects.

Other parameters are:

• state - the state that should be applied to the services listed in service_selection. Expects the numeric ID for state.
• comment - free text comment that should be given to the state change.

Example input: /rest/status?svc.serviceid=1&svc.serviceid=2

{
   "new_state" : "0",
   "comment" : "This is a known unknown"
}

Example output:

{
   "summary" : {
      "num_services" : "2",
      "num_hosts" : "0"
   },
   "list" : {
      "hosts" : [],
      "services" : [
         {
            "id" : "1",
            "hostname" : "host1",
            "servicename" : "service on host1"
         },
         {
            "id" : "2",
            "hostname" : "host2",
            "servicename" : "service on host2"
         }
      ]
   }
}

Access required: VIEWPORTACCESS, VIEWSOME or VIEWALL

Any public hashtags will be included in object permissions.
URL: /rest/status/viewport

• GET - lists summarised information about hashtags
• PUT, POST, DELETE - unimplemented

URL parameters:

• keyword - filter by these hashtags/keywords. Can be repeated.
• single_hashtag - if set, this is effectively the same as /rest/status/viewport/SINGLE_HASHTAG.
• host - filter hosts by this host name. Can be repeated.
• servicecheck - filter services by this service check name. Can be repeated.
• filter - either handled or unhandled. Filters services by this condition.
• host_filter - either handled or unhandled. Filters host by this condition.
• state - filters by services in this state. Expects the numeric id for state. Can be repeated.
• host_state - filters by hosts in this state. Expects the numeric id for state. Can be repeated.
• rows - Use this to restrict the number of hashtags returned in the list. If not specified, will return all results. NOTE: The summary hash in the response will give the information for the entire list of hashtags, not just the ones returned with rows - this is liable to change so do not depend on it

Example response:

{
   "summary" : {
      "handled" : "15",
      "unhandled" : "31",
      "service" : {
         "handled" : "3",
         "unhandled" : "31",
         "unknown" : "34",
         "total" : "34"
      },
      "total" : "46",
      "host" : {
         "handled" : "12",
         "unhandled" : "0",
         "down" : "1",
         "up" : "11",
         "total" : "12"
      }
   },
   "list" : [
      {
         "hosts" : {
            "handled" : "1",
            "unhandled" : "0",
            "down" : {
               "handled" : "1"
            },
            "total" : "1"
         },
         "services" : {
            "handled" : "1",
            "computed_state" : "unknown",
            "unhandled" : "0",
            "unknown" : {
               "handled" : "1"
            },
            "total" : "1"
         },
         "computed_state" : "critical",
         "downtime" : null,
         "name" : "allhandled",
         "description" : "All services handled"
      },
      {
      ...
      }
   ]
}

Note: The computed_state keyword represents the highest state based on host state and service state. Specifically, this will return critical if the host is down or unreachable otherwise the service computed_state.

Access: VIEWPORTACCESS, VIEWSOME, or VIEWALL
URL: rest/status/viewport/*

• GET - lists summarised information about hashtag
• PUT, POST, DELETE - unimplemented

This is effectively a 'Services' search with keyword set to be the first argument.
However, if a user does not have VIEWSOME or VIEWALL, then only public hashtags will be visible.

URL: /rest/status/performancemetric

• GET - lists performance metrics with values and uoms
• PUT, POST, DELETE - unimplemented

Filtering URL parameters:

• hostgroupid - includes this host group in list. Can be repeated.
• hostgroupname - includes this host group in list. If the name is associated with more than one host group, all will be included in the response. Can be repeated.
• hostname - filter hosts by this host name. Can specify wildcards with %25. Can be repeated.
• hostid - filter hosts by this host id number. Can be repeated.
• servicename - filter services by this service check name. Can specify wildcards. Can be repeated.
• serviceid - filter services by this service id number. Can be repeated.
• metricname - filter metrics by this metric name. Can be repeated.
• hs - filter based on this host service. Of the form hostname::servicename. Can be repeated.
• hsm - filter based on this host service metric. Of the form hostname::servicename::metricname. Can be repeated.
• convertuom - if set, will convert performance data into base units. Eg, if value=1500 and uom=MB, with this flag set, will return value=1500000000 uom=bytes.

Other URL parameters:

• rows - limit results by this many rows. Note: if ordering by value, Opsview needs to check for all services before sorting, so we recommend you filter the list of performance metrics to have a smaller set first.
• order - you can suffix with _desc to sort descending. You can specify multiple values to have secondary sorting (except when sorting by value).
  • hostname
  • servicename
  • metricname
  • value - If this is set, will order by value, then hostname, servicename. Values of empty strings will be sorted to the bottom of the list, regardless of ascending or descending.

Example output:

{
    "list": [{
        "hostname": "opcollector",
        "metricname": "age",
        "servicename": "Opsview Housekeep Age",
        "servicestate": "critical",
        "uom": "",
        "value": "5"
    }, {
        "hostname": "opsview",
        "metricname": "rta",
        "servicename": "TCP/IP - LAN",
        "servicestate": "unknown",
        "uom": "ms",
        "value": "25"
    }, {
        "hostname": "winvpn",
        "metricname": "rta",
        "servicename": "TCP/IP - LAN",
        "servicestate": "unknown",
        "uom": "",
        "value": ""
    }],
    "rows": "3",
    "total": "5"
}

It is possible for the value to be the empty string - this means the value is not available (for instance, if the service has a response without any performance dat

This section is for searching for live objects being monitored by Opsview. This is in the Runtime database, hence the URL path is /rest/runtime/{objecttype}.

URL: /rest/runtime/service. Requires authentication - requires VIEWALL or VIEWSOME permission

• GET - returns available objects, either grouped by host or grouped by service
• POST, PUT, DELETE - not implemented

Access Control

VIEWALL allows all objects to be returned.
VIEWSOME allows objects to be returned where permission has been granted based on the access object selection.

Retrieving Host or Service Lists

The same parameters as searching based on service filtering can be used.
Additional parameters:

• rows - returns back this number of rows. Defaults to 50 rows.
• group_by - returns results based on either host or service. Defaults to host.
• distinct - if set to 1, then only a distinct list of hosts or services are returned. This means you are searching for host names or service names rather than a host+service combination.

Response:

• rows - the number of actual rows returned.
• allrows - the total number of rows based on filtering parameters.
• total - the total number of rows if filtering is not applied.
• list - an array of the results.

Example response, if group_by=host and distinct=0:

{
   "allrows" : "30",
   "list" : [
      {
         "list" : [
            "Another exception",
            "Coldstart",
            "Test exceptions"
         ],
         "name" : "cisco"
      },
      {
         "list" : [
            "Another exception",
            "Coldstart"
         ],
         "name" : "cisco1"
      }
   ],
   "rows" : "5",
   "total" : "50"
}

Example response if group_by=service and distinct=0:

{
   "allrows" : "30",
   "list" : [
      {
         "list" : [
            "cisco",
            "cisco1",
            "cisco2",
            "cisco3",
            "cisco4"
         ],
         "name" : "Another exception"
      }
   ],
   "rows" : "5",
   "total" : "50"
}

Example response if group_by=host and distinct=1:

{
   "allrows" : "12",
   "list" : [
      {
         "name" : "cisco"
      },
      {
         "name" : "cisco1"
      },
      {
         "name" : "cisco2"
      },
      {
         "name" : "cisco3"
      },
      {
         "name" : "cisco4"
      }
   ],
   "rows" : "5",
   "total" : "15"
}

Example response if group_by=service and distinct=1:

{
   "allrows" : "12",
   "list" : [
      {
         "name" : "Another exception"
      },
      {
         "name" : "Check Loadavg"
      },
      {
         "name" : "Check Memory"
      },
      {
         "name" : "Coldstart"
      },
      {
         "name" : "faked ok service"
      }
   ],
   "rows" : "5",
   "total" : "19"
}

This section is for searching for live objects being monitored by Opsview. This is in the Runtime database, hence the URL path is /rest/runtime/{objecttype}.

URL: /rest/runtime/performancemetric. Requires authentication - requires VIEWALL or VIEWSOME permission.

• GET - returns available performance metric objects
• POST, PUT, DELETE - not implemented

Access Control

VIEWALL allows all performance data to be returned.
VIEWSOME allows performance data to be returned for objects where permission has been granted for the service based on the access object selection.

Requesting Performance Metrics

Performance metrics consist of a name of the format:

{hostname}::{servicename}::{metricname}

For example, a fully qualified metric name is opsview::Opsview NDO::ndo_file_backlog.
Parameters:

• type - this determines the type of results returned. If host is selected, then a set of unique host names will be returned where metrics exist based on the search parameters. Other possible values are: service, metric keyword and hostgroup. If this value is not set, then the fully qualified metric names will be returned.
• host - search host name based on these filters. Can use % as a wildcard. Can be repeated.
• service - search service name based on these filters. Can use % as a wildcard. Can be repeated.
• metric - search metric name based on these filters. Can use % as a wildcard. Can be repeated.
• htid - search for performance metrics on services by this host template id. Can be repeated.
• keyword - search metrics related to this keyword name. Can be repeated.
• hostgroupid - search metrics where its host is contained anywhere in this host group hierarchy. Can be repeated.
• bcid - search metrics based on this business component id. Can be repeated. If the user does not have BSM access, no performance metrics will be matched. Only business components that this user has access to will be searched. If the system does not have the BSM feature, an error will be returned.
• rows - returns back this number of rows. Defaults to all rows.
• order - orders results based. Can be repeated. Valid values are host, service, metric, hostgroup.
• format - if set to object and type=hostgroup or keyword, will return the list of data in an object format. This is required for host groups because they are uniquely identified by their id.
• collapse_multiple_services - this reduces multiple services into a single response. For instance, the response with collapse_multiple_services=0 would be [“Disk: /”, “Disk: /var”, “Disk: /home”, “Interface: eth1”, “Interface: eth0”], but the response with collapse_multiple_services=1 would be ['Disk:', 'Interface:']. This only applies where type=service. Default is 0.
• hsm - if set, will filter by this particular hsm. Can be repeated.

Response:

• rows - be the number of actual rows returned.
• total - the total number of rows if filtering is not applied.
• list - an array of the results.

Note: This will only return items that have performance data. If you want to search for all hosts, use /rest/runtime/host.
Example response for type=host:

{
   "rows" : "13",
   "list" : [
      "build-sol10-amd64",
      "build-sol10-i386",
      "ov-build-centos4-32",
      "ov-build-centos4-64",
      "ov-build-centos5-32",
      "ov-build-centos5-64",
      "ov-build-etch-32",
      "ov-build-etch-64",
      "ov-build-hardy-32",
      "ov-build-hardy-64",
      "ov-build-lenny-64",
      "ov-build-rhel5-32",
      "ov-build-rhel5-64"
   ],
   "total" : "41"
}

Example response for type=service:

{
   "rows" : "6",
   "list" : [
      "/",
      "/backup",
      "/boot",
      "/home",
      "/srv/vms",
      "/var"
   ],
   "total" : "48"
}

Example response for type=metric:

{
   "rows" : "2",
   "list" : [
      "boot",
      "root"
   ],
   "total" : "279"
}

Example response for type=hostgroup&format=object:

{
   "list" : [
      {
         "id" : "4",
         "name" : "Opsview,UK,Leaf,"
      },
      {
         "id" : "2",
         "name" : "Opsview,UK,Monitoring Servers,"
      },
      {
         "id" : "5",
         "name" : "Opsview,UK2,Leaf2,"
      }
   ],
   "rows" : "3",
   "total" : "3"
}

Example response for type not set (ie, the fully qualified metric name):

{
   "list" : [
      "opcollector::/::root",
      "opsview::/::root",
      "ov-build-centos5-64::/::root",
      "ov-build-hardy-32::/::root",
      "ov-build-hardy-64::/::root",
      "ov-build-rhel5-64::/::root",
      "prodservice1::/boot::boot",
      "prodservice1::/::root",
      "prodweb3::/::root",
      "vmhost1::/boot::boot",
      "vmhost1::/::root",
      "vmhost2::/::root",
      "vmhost3::/::root",
      "vmhost3::/srv/vms::root"
   ],
   "rows" : "14",
   "total" : "455"
}

This section is for searching for live objects being monitored by Opsview. This is in the Runtime database, hence the URL path is /rest/runtime/{objecttype}.

URL: /rest/runtime/monitoringclusters.

Requires authentication - requires VIEWALL or VIEWSOME permission.

• GET - returns monitoring clusters
• POST, PUT, DELETE - not implemented

Access Control

• VIEWALL allows all monitoring clusters to be returned.
• VIEWSOME only lists monitoring clusters that are associated to objects where permission has been granted based on the access object selection.

Retrieving Monitoring Clusters

Response:

• list - an array of the results

Where list is an associative array of the results, consisting of:

• id - ID number of the monitoring cluster. id=1 means it is the primary cluster
• name - Name of the monitoring cluster
• activated - Either 0 or 1

Example response:

{
    "list": [
        {
            "activated": "1",
            "id": 1,
            "name": "Master Monitoring Server",
            "passive": "0"  // Unused
        },
        {
            "activated": "1",
            "id": 2,
            "name": "ClusterA",
            "passive": "0"
        },
        {
            "activated": "1",
            "id": 3,
            "name": "Cluster",
        }
    ],
}

This section is for searching for live objects being monitored by Opsview. This is in the Runtime database, hence the URL path is /rest/runtime/{objecttype}.

URL: /rest/runtime/network. Requires authentication - requires VIEWALL or VIEWSOME permission.

• GET - returns network topology map
• POST, PUT, DELETE - not implemented

Access Control

VIEWALL allows all hosts to be returned.
VIEWSOME allows only hosts where permission has been granted based on the access object selection.

Retrieving Topology Map

Parameters:

• hostgroupid - includes this host group (by id) in list. Can be repeated. Note, this will return all hosts in this hosgroupid and below in the hierarchy (so a hostgroupid of 1 effectively returns all hosts).
• fromhostname - if set, then only the host descendants will be returned. Can be repeated.
• host - filter hosts by this host name. Can be repeated.
• only_with_children - if set, then only hosts with at least 1 child are returned.
• monitoredby - if set, filter hosts if it is monitored by the monitoring server by this id.
• rows - if set, sets the maximum of rows requested.

Response:

• rows - the number of actual rows returned.
• allrows - the total number of rows based on filtering parameters.
• total - the total number of rows if filtering is not applied.

• list - an associative array of:

  • name - name of the host
  • children - this will be a list of the children nodes by host name
  • parents - this will be a list of the parents nodes by host name

Note: If due to permission restriction children/parents are not visible null will be used instead of host name.
Example response:

{
    rows    => 4,
    total   => 20,
    allrows => 8,
    list    => [
        {
            name: "opsview",
            parents: [],
            children: [ "opsviewdev1", null, "cisco" ]
        },
        {
            name: "opsviewdev1",
            parents: [ "opsview" ],
            children: []
        },
        {
            name: "cisco",
            parents: [ "opsview" ],
            children: [ "monitored_by_collector", "cisco4" ]
        },
        {
            name: "cisco4",
            parents: [ "cisco" ],
            children: [ null ]
        }
    ]
}

This section is for searching for live objects being monitored by Opsview. This is in the Runtime database, hence the URL path is /rest/runtime/{objecttype}.

URL: /rest/runtime/hosttemplate. Requires authentication - requires VIEWALL or VIEWSOME permission.

• GET - returns all host templates
• POST, PUT, DELETE - not implemented

Access Control

VIEWALL allows all host templates to be returned.
VIEWSOME allows only host templates that are associated to hosts where permission has been granted based on the access object selection.

Retrieving Host Templates

Parameters:

• hostgroupid - filters host templates based on this host group id, from here downwards. Can be repeated.
• hostname - filters host templates based on this hostname. Can be repeated.
• has_perfdata - if set, filters host templates so only contains services with performance data. Default unset.

Response:

• rows - the number of actual rows returned.
• allrows - the total number of rows based on filtering parameters. Note, since there is no filtering, this will always be total.
• total - the total number of rows if filtering is not applied.

• list - array of associative arrays of:

  • id - host template id
  • name - name of the host template

Example response:

{
  allrows => 4,
  list    => [
               { id => 7, name => "Agent only" },
               { id => 1, name => "Base Unix" },
               { id => 3, name => "Cisco Mgt" },
               { id => 2, name => "Network - Base" }
             ],
  rows    => 4,
  total   => 4,
}

URL: /rest/acknowledge. This requires authentication. Requires ACTIONSOME or ACTIONALL access.

• GET - lists all hosts and services that can be acknowledged based on state and user permissions
• POST - submit an acknowledgement
• PUT - not implemented
• DELETE - remove the acknowledgement as matched by the object selection

Access Control

• ACTIONALL allows setting acknowledgements to any object in Opsview.
• ACTIONSOME allows setting of acknowledgements to host or services based on the access object selection.

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

Object Selection

Acknowledgements are set against host or service objects.
You can choose hosts or services using the same URL parameters as the status API, with the following 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:

• hosts:

  • 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)

• services:

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

If you request a specific object (using 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 acknowledgements" }

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.

You will get a list of services, same as /rest/status/service, but with the following filtering:

• only hosts or services in an unhandled state will be shown.
• only objects that the user will have access to acknowledge will be listed.

See the status API for details of the search parameters and the output.

Attributes required for setting an acknowledgement:

• comment - free text comment regarding acknowledgement. Required.
• notify - whether notification should be sent. Defaults to no.
• sticky - whether the acknowledgement should be sticky or not. Defaults to no.

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

{
    comment => "Covered in ticket number 5675",
    notify => 1,
    sticky => 0,
}

If the same parameter is found as input data and in the URL, the input data has priority.
The author of the acknowledgement is taken from the user login information.
Acknowledgements are set asynchronously, so the REST API will return as soon as the acknowledgement submission is entered. There maybe a small delay before the acknowledgement is displayed in the user interface.
On successful submission of acknowledgements, the response will be of the form:

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

This reflects the number of hosts and services that this acknowledgement applied to.
In the event of a failure, the response will be:

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

Where message will be one of:

• Error validating acknowledge parameters.
• No objects chosen for acknowledgements (this could also appear if the user does not have access to the objects specified).
• Errors setting acknowledgements - some objects may have been acknowledged.
• Error when searching for objects.

URL: /rest/recheck. This requires authentication. Requires ACTIONSOME or ACTIONALL access.

• GET - lists all hosts and services that can be re-checked based on user permissions
• POST - submit an recheck request
• PUT, DELETE - not implemented

The GET request will only list objects that can be rechecked (i.e., service checks of check type Active or SNMP Polling or are cascaded from another check, or hosts).

The POST request will only apply on objects that can be rechecked.

Access Control

• ACTIONALL allows submitting a recheck to any object in Opsview.
• ACTIONSOME allows submitting a recheck to host or services based on the access object selection.

Note: If a user has ACTIONALL, but only VIEWSOME, the user could submit rechecks for objects that they cannot view.

Object Selection

See the selection of objects in the acknowledge documentation as it uses the same routines.

You will get a list of services, same as /rest/status/service, but with the following filtering:

• Only objects that the user will have access to recheck will be listed.

See the status API for details of the search parameters and the output.

Re-checks are set asynchronously, so the REST API will return as soon as the submission is entered. There maybe a small delay before the result is displayed in the user interface. On successful submission of re-checks, the response will be of the form:

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

This reflects the number of hosts and services that this re-check applied to.

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

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

Where message will be one of:

• No objects chosen for recheck (this could also appear if the user does not have access to the objects specified).
• Errors setting recheck - some objects may have been rechecked.
• Error when searching for objects.

Example

You can use the below example call to force a recheck of all services against a given host:

./opsview_rest --pretty --username=USERNAME --password=PASSWORD POST "recheck?hostname=HOSTNAME&servicename=%"

If you only want to recheck the host and not any services on it, use:

./opsview_rest --pretty --username=USERNAME --password=PASSWORD POST "recheck?hostname=HOSTNAME&includehosts=1&type=host"

URL: /rest/graph. This requires authentication. Requires RRDGRAPHS permission as well as VIEWALL or VIEWSOME permission.

• GET - returns performance data for requested objects.
• POST, PUT, DELETE - not implemented.

Access Control

• RRDGRAPHS allows access to this end point.
• VIEWALL allows performance data for all objects to be returned.
• VIEWSOME allows performance data to be returned for objects where permission has been granted for the service based on the access object selection.

Parameters:

• end - expected as number of epoch seconds. Defaults to now.
• start - epoch seconds. Defaults to end subtract 1 day duration. This has priority over duration.

• duration - specify duration. Use h, d, w for hours, days, weeks respectively. m is assumed to be minutes - use months and minutes for clarity. (Note: This parameter used to be based on RRDtool format, but is now a custom format to Opsview). Default: 1d. Examples:

  • 3145h - 3145 hours
  • 131d1h - 131 days and 1 hour
  • 18w5d1h - 18 weeks, 5 days and 1 hour

• hsm - in the format of hostname::servicename::metricname. Can be repeated. If the performance metric is not found, it is ignored from the response.

• keyword - search for all hsms related to the specified keyword. Can be repeated. Be aware this could return a large amount of data if there are matches to lots of hsms
• hostname - search for all hsms related with this host name. Can have wildcards. Can be repeated.
• servicename - search for all hsms related with this service name. Can have wildcards. Can be repeated.
• metricname - search for all hsms with this metric name. Can have wildcards. Can be repeated.
• include_offset_timezone. Defaults to 0. Set this to 1 to adjust the time value so that the current timezone offset from UTC (based on the Opsview server) is included in the time value. This is not required in most cases.

Example response:

{
  list => [
    {
      data => [
        [1242849600, 517],  // Time in Unix epoch seconds and value at this time
        [1242936000, 517],  // Note: The value could be null/empty string to mean "no value at this time" - this should be represented as a gap in any graphs
        ....
        [1254168000, 505],
      ],
      description => "Min: 505.000<br />Max: 517.000<br />Average: 511.305",
      label => "opsview::Opsview HTTP::size",
      uom => "bytes",
    }
  ],
}

The time parameter is the number of seconds since epoch. This time is returned back in UTC format. See the include_offset_timezone parameter if you want this value adjusted based on the timezone. Note, it is not possible to return this value as a date time formatted string.

URL: /rest/event. This requires authentication. Requires VIEWALL or VIEWSOME permission.

• GET - returns event data for requested objects
• POST, PUT, DELETE - not implemented

An event is considered to be either:

• a host or service changing state (eg, from OK to CRITICAL).
• a host or service result during soft failures (eg, CRITICAL SOFT 1 to CRITICAL SOFT 2).
• a host or service in a failure state where alert every failure is enabled.
• an acknowledgement
• a downtime start
• a downtime stop (or cancel)

Access Control

• VIEWALL allows all event data to be returned.
• VIEWSOME allows event data to be returned for objects where permission has been granted for the service based on the access object selection.

Parameters:

• cols - defines which columns of data to return. Acceptable values: hostname, time, objectid, servicename, state, state_type, output, eventid, host_group, host_group_id, markdown_filter, htid, bcid, bsid. Note that some columns will always be returned. For multiple columns use: cols=state&cols=hostname.
• startTime - filter by start time, eg. 2011-11-01 18:43:22. Time is based on the server's timezone.
• endTime - filter by end time.
• rows - the number of rows to return.
• page - which page of data to return.
• sortby - a json structure to describe the ordering of results. Defaults to [{“col”:“time”,”order”:“desc”}].
• host_state - host states to filter on. Can be repeated. Acceptable values: up/0, down/1, unreachable/2.
• service_state - service states to filter on. Can be repeated. Acceptable values: ok/0, warning/1, critical/2, unknown/3.
• host - host names to filter on. Can be repeated.
• service - service - service names to filter on. Can be repeated. Note: there is a limitation that if you filter by service name only, you will get results for all hosts, whether they have the specified service or not
• serviceonly - if set, will only return services. Otherwise returns host as well as service events. Default unset.
• state_type - state type to filter on. Acceptable values: soft/0, hard/1.
• host_group - host group to filter on. Can be anywhere in the hierarchy. Can be repeated.
• keyword - keyword to filter on. Can be repeated.
• htid - host template ID. Can be repeated.
• bsid - business service ID. Can be repeated.
• bcid - business component ID. Can be repeated.
• search - search terms. Will search in host name, service name or output. Can be repeated to produce an AND effect.
• saved_maxeventid - if set with the value of the last max event id, an extra attribute will be in the result to signify the number of new events since the last max event id (based on the filtering parameters).
• eventtype - there are 4 types of events: 0 = state change event; 1 = acknowledgements event; 2 = downtime start event; 3 = downtime end event. If no eventtype is specified, only eventtype=0 is returned, otherwise specify multiple times to get different types added.
• include_max - if set to 0, will not include the max id data. This can be much quicker on the database to not run this query. Defaults to 1
• include_page_summary - if set to 0, will not include the page number data. This can be much quicker on the database to not run this query. Defaults to 1

Example response:

{
   "list" : [
      {  
         "eventid" : "9373",
         "eventtype" : "0",   # State change event
         "markdown" : "0",   
         "objectid" : "194",
         "output" : "OK - load average: 1.53, 1.73, 1.58",
         "servicename" : "Check Loadavg",
         "state" : "ok",
         "state_type" : "hard",
         "time" : "1248858348"
      },
      {
         "ack_author" : "admin",
         "ack_comment" : "Due to power failure",
         "eventid" : "9372",
         "eventtype" : "1",
         "objectid" : "194",
         "servicename" : "Check Loadavg",
         "state" : "ok",
         "state_type" : "hard",
         "time" : "1248858348",
      },
      {
         "downtime_author" : "admin",
         "downtime_comment" : "Offline for repairs",
         "downtime_end" : "1248860000",
         "downtime_start" : "1248858348",
         "eventid" : "9370",
         "eventtype" : "2",   # Downtime start event. Same for eventtype=3
         "markdown" : "0",   
         "objectid" : "194",
         "output" : "OK - load average: 1.53, 1.73, 1.58",
         "servicename" : "Check Loadavg",
         "state" : "ok",
         "state_type" : "hard",
         "time" : "1248858348",
      },
      ...
  ],
  "summary" : {
      "entries" : "10",
      "filtered_maxeventid" : "9373",
      "filtered_new_event_count" : "2",
      "maxeventid" : "9373",
      "page" : "1",
      "pages" : "85",
      "total_entries" : "843"
   }
}

The time, downtime_start and downtime_end parameters are the number of seconds since epoch which by definition is in the UTC time zone.

Note: that some fields are conditional and will only be displayed if appropriate.

URL: /rest/notes/OBJECTTYPE/ID.

Requires authentication.

The object types are:

• Host (host). Can also use /rest/notes/host?hostname=X
• Service (service). Can also use /rest/notes/service?hostname=X&servicename=Y
• Host Group (hostgroup). Can also use /rest/notes/hostgroup?hostgroupid=X
• Business service (bsmservice)
• Component (bsmcomponent)

Access Control

Access control is based on the object types:

• host - requires VIEWALL or VIEWSOME with this object to view. Requires ACTIONSOME to edit. ID is based on the opsview host id.
• service - requires VIEWALL or VIEWSOME for this object to view. Requires ACTIONSOME to edit. ID is based on the nagios_object_id number
• bsmservice - requires view access based on BSM permissions to view. Requires edit access to edit.
• bsmcomponent - requires view access based on BSM permissions to view. Requires edit access to edit.

Input:

opsview_rest --username=admin --password=password --data-format=json --pretty GET /rest/notes/host/7

Returns:

{
   "id" : "7",
   "note" : "This is a host note",
   "writeable" : "1"
}

The note will be in a mini HTML format.

Error conditions:

• Invalid id or no permission on host - 404

Input:

/opt/opsview/coreutils/bin/opsview_rest --username=admin --password=password --data-format=json --pretty PUT /rest/notes/host/7 --data='{ "note" : "New host note" }'

Returns:

{
   "id" : "7",
   "note" : "New host note",
   "writeable" : "1"
}

To clear a note, set note to an empty string.

There will be an error if no note parameter is set.

Below is an example:

{
/opt/opsview/coreutils/bin/opsview_rest --username=admin --password=password --data-format=json --pretty PUT /rest/notes/host/7 --data='{ "note" : "

TEST1111

" }' {
"id" : "7",
"note" : "

TEST1111

",
"writeable" : "1"
}
}

URL: /rest/queryhost. This requires authentication. Requires CONFIGUREHOSTS access options.

• GET - Not implemented.
• POST - Returns a list of interfaces on the device it queries.
• PUT - Not implemented.
• DELETE - Not implemented.

Access Control

CONFIGUREHOSTS allows to query any SNMP object in Opsview.

Valid parameters are:

• hostname - hostname of the server as stored within the database. Required
• ip - Hostname or IP address. Required if not using hostname or if this is a new host
• snmp_version - one of 1, 2c or 3. Required if not using hostname or if this is a new host
• hostid - hostid of the host from the DB. Not required if this is a new host.
• msid - the monitoring cluster that the query is to be run from. Will use the first node if it is a cluster. Can be set to the primary collector, which is set to 1. Default is primary.
• snmp_port - port for snmp to listen for devices. Defaults to 161.

The remaining parameters for QueryHost depends on the version of SNMP requested.

Version 1 and 2c

The parameters required are:

• snmp_community - the community string

Version 3

Extra information is required to satify the snmpv3 credentials. These must be added to the call.

• snmpv3_username
• snmpv3_authpassword
• snmpv3_authprotocol
• snmpv3_privpassword
• snmpv3_privprotocol

Listing interfaces

Output of a list response:

{
  interfaces => [
    {
      discards_critical => 15,
      discards_warning => "",
      errors_critical => 10,
      errors_warning => "",
      extra_info => "alias:'' speed:'' link:'' status:''",
      id => 0,
      ifAlias => undef,
      ifDescr => "",
      ifLink => undef,
      ifSpeed => undef,
      ifStatus => undef,
      interfacename => "",
      throughput_critical => "0:50%",
      throughput_warning => "",
    },
    {
      discards_critical => "",
      discards_warning => "",
      errors_critical => "",
      errors_warning => "",
      extra_info => "alias:'192.168.13.0 network' speed:'10Mbit/s' link:'up' status:'up'",
      id => 1,
      ifAlias => "192.168.13.0 network",
      ifDescr => "Ethernet0/0",
      ifLink => "up",
      ifSpeed => "10Mbit/s",
      ifStatus => "up",
      interfacename => "Ethernet0/0",
      throughput_critical => "",
      throughput_warning => "",
    },
    {
      discards_critical => "",
      discards_warning => "",
      errors_critical => "",
      errors_warning => "",
      extra_info => "alias:'192.168.21.0 network' speed:'10Mbit/s' link:'down' status:'down'",
      id => 3,
      ifAlias => "192.168.21.0 network",
      ifDescr => "Ethernet0/1",
      ifLink => "down",
      ifSpeed => "10Mbit/s",
      ifStatus => "down",
      interfacename => "Ethernet0/1",
      throughput_critical => "",
      throughput_warning => "",
    },
    {
      discards_critical => "",
      discards_warning => "",
      errors_critical => "",
      errors_warning => "",
      extra_info => "alias:'' speed:'8Gbit/s' link:'up' status:'up'",
      id => 5,
      ifAlias => "",
      ifDescr => "Loopback0",
      ifLink => "up",
      ifSpeed => "8Gbit/s",
      ifStatus => "up",
      interfacename => "Loopback0",
      throughput_critical => "",
      throughput_warning => "",
    },
    {
      discards_critical => "",
      discards_warning => "",
      errors_critical => "",
      errors_warning => "",
      extra_info => "alias:'' speed:'10Gbit/s' link:'up' status:'up'",
      id => 4,
      ifAlias => "",
      ifDescr => "Null0",
      ifLink => "up",
      ifSpeed => "10Gbit/s",
      ifStatus => "up",
      interfacename => "Null0",
      throughput_critical => "",
      throughput_warning => "",
    },
    {
      discards_critical => "",
      discards_warning => "",
      errors_critical => "",
      errors_warning => "",
      extra_info => "alias:'192.168.250.0 network' speed:'2Mbit/s' link:'up' status:'down'",
      id => 2,
      ifAlias => "192.168.250.0 network",
      ifDescr => "Serial0/0",
      ifLink => "up",
      ifSpeed => "2Mbit/s",
      ifStatus => "down",
      interfacename => "Serial0/0",
      throughput_critical => "",
      throughput_warning => "",
    },
    {
      discards_critical => "",
      discards_warning => "",
      errors_critical => "",
      errors_warning => "",
      extra_info => "alias:'' speed:'100Mbit/s' link:'up' status:'up'",
      id => 7,
      ifAlias => "",
      ifDescr => "Virtual-Access1",
      ifLink => "up",
      ifSpeed => "100Mbit/s",
      ifStatus => "up",
      interfacename => "Virtual-Access1",
      throughput_critical => "",
      throughput_warning => "",
    },
    {
      discards_critical => "",
      discards_warning => "",
      errors_critical => "",
      errors_warning => "",
      extra_info => "alias:'' speed:'100Mbit/s' link:'up' status:'down'",
      id => 8,
      ifAlias => "",
      ifDescr => "Virtual-Access2",
      ifLink => "up",
      ifSpeed => "100Mbit/s",
      ifStatus => "down",
      interfacename => "Virtual-Access2",
      throughput_critical => "",
      throughput_warning => "",
    },
    {
      discards_critical => "",
      discards_warning => "",
      errors_critical => "",
      errors_warning => "",
      extra_info => "alias:'' speed:'100Mbit/s' link:'up' status:'down'",
      id => 6,
      ifAlias => "",
      ifDescr => "Virtual-Template1",
      ifLink => "up",
      ifSpeed => "100Mbit/s",
      ifStatus => "down",
      interfacename => "Virtual-Template1",
      throughput_critical => "",
      throughput_warning => "",
    },
  ],
  system_description => "Cisco Internetwork Operating System Software",
}

Testing Connection

{
    system_description => "Cisco Internetwork Operating System Software",
}

This REST API returns detailed information about a particular host or service check.

URL: /rest/detail

• Host: /rest/detail?hostname=X
• Service: /rest/detail?hostname=X&servicename=Y

Parameters:

• includehandleddetails=1 - if set, will return ack_author and ack_comment when a host or a service is acknowledged.
• include_recheckable=1 - if set then the response will include recheckable=0 or 1 based on whether it is possible to recheck this host or service

NOTE: From version 6.0, the last_notification and next_notification details have been removed from the returned output as they are not relevant anymore

Methods:

• GET - returns data about the object. Requires VIEWSOME or VIEWALL
• POST - set actions for the object. Requires ACTIONSOME or ACTIONALL
• PUT/DELETE - unimplemented

You can choose hosts or services using the same URL parameters as the status API

The endpoint will return data similar to the following:

{
 "object": {
  "hostname": "opsview",
  "servicename": "HTTP",              // Does not exist for host detail
  "state": "UP",                      // Possible values: 
                                      //   For host: UP, DOWN, UNREACHABLE. 
                                      //   For Service: OK, WARNING, CRITICAL, UNKNOWN
  "alias": "host description",        // Host description
  "ip": "localhost",                  // IP field for the host
  "state_duration": 1880,             // number of seconds
  "output": "OK - localhost: rta 0.0.29ms lost 0%", // Text to display. Maybe long so needs to wrap. Max 16K
  "perfdata": "rta=0.0.29ms;500.000;1000.000", // Text. Maybe long so needs to wrap. Max 16K
  "current_attempt": 1,               // Number
  "max_attempts": 2,                  // Number. Always lower than current_attempt
  "state_type": 0,                    // 0=soft, 1=hard
  "last_check": 1234567890,           // epoch seconds. 0 = not been checked
  "monitored_by": "Collector",          // Name of monitoring cluster. Could be null if monitoring collector is deleted
  "check_type": 1,                    // Options: 1 = Active Plugin, 2 = Passive, 4 = SNMP Trap, 5 = SNMP Polling. Could be null to be unknown
  "latency": 0.000,
  "duration": 0.003,
  "next_check_expected": 1234567890,  // epoch seconds. If 0, not known
  "last_state_change": 1234567890,    // epoch seconds
  "acknowledged": 0,                  // 0=no, 1=yes. If host or service is acknowledged
  "is_flapping": 1,                      // 0=no, 1=yes
  "in_downtime": 0,                   // 0=no, 1=yes
  "status_update_time": 1234567890,   // epoch seconds. When the last result was received
  "active_checks": 1,                 // 0=no, 1=yes. If active checks enabled
  "active_checks_services_enabled": 9 // Number of services with active checks enabled on this host. Not present for services
  "passive_checks": 0,                // 0=no, 1=yes. If passive checks enabled
  "notifications": 1,                 // 0=no, 1=yes. If notifications enabled
  "notifications_services_enabled": 7 // Number of services with notifications enabled on this host. Not present for services
  "event_handler": 1,                 // 0=no, 1=yes. If event handler enabled
  "flap_detection": 1,                // 0=no, 1=yes. If flap detection enabled
  "can_testservicecheck": 1,          // Tells front end if this service is testable. Will not exist if not. Not present for hosts
  "num_interfaces": 3,                // Number of interfaces on this host. Not present for services
  "total_services": 9,                // Number of services on this host
  "perfdata_available": 1,            // 0=no, 1=yes. If performance data is available for this service. Not present for hosts
  "unhandled": 0,                     // 1=unhandled, 0=handled. Not present for hosts
 }
}

Note: last_notification and notification_number is removed in 6.0 as this is no longer stored at the object level.

Input:

{
 "notifications": { "enabled": 0 }
}

Output:

{"success": "1"}

Possible input values for host:

{ 
 "active_checks": { 
  "host_enabled": 0, // or 1
  "services_enabled": 1 // or 0
 },
 "passive_checks": {
  "enabled": 0, // or 1
 },
 "set_state": {
  "result": 0, // 0=UP, 1=DOWN, 2=UNREACHABLE
  "output": "Plugin output", // Must be set not empty
  "perfdata": "time=9",      // Optional
 },
 "notifications": {
  "host_enabled": 0, // or 1
  "services_enabled": 0, // or 1
 },
 "event_handler": {
  "enabled": 0, // or 1
 },
 "flap_detection": {
  "enabled": 0, // or 1
 },
 "recheck": {
  "check_host": 0,       // or 1. If both are 0, then nothing is sent to the Orchestrator
  "check_services": 0, // or 1
  "time" : 1234567890, // Epoch seconds. Default now
 }
}

Possible input for services:

{ 
 "active_checks": { 
  "enabled": 0, // or 1
 },
 "passive_checks": {
  "enabled": 0, // or 1
 },
 "set_state": {
  "result": 0, // 0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN
  "output": "Plugin output", // Must be set not empty
  "perfdata": "time=9",      // Optional
 },
 "notifications": {
  "enabled": 0, // or 1
 },
 "event_handler": {
  "enabled": 0, // or 1
 },
 "flap_detection": {
  "enabled": 0, // or 1
 },
 "recheck": {
   "time" : 1234567890, // Epoch seconds. Default now
 }
}

This REST API is able to run tests against an active plugin service check so that we can get an immediate response without going via the entire monitoring engine. This is useful for troubleshooting.

Requires TESTSOME or TESTALL.

It is possible to change the arguments to use on the plugin, if the user has TESTCHANGE permission.

Note: This will not execute the check exactly as the monitoring system would do as there are some environment variables that cannot be set appropriately via the REST API..

URL: /rest/testservicecheck?hostname=X&servicename=Y

Only works for services

Methods:

• GET - Retrieves data for the test service check tab
• POST - Executes the test service check
• PUT/DELETE - unimplemented

Parameters:

• hostname & servicename - to identify the specific service check

Returns:

{
 "pluginname": "check_tcp", // Plugin name
 "args": "-H $HOSTNAME$",   // args used for check. Will consider host exceptions. If sensitive_arguments is set on service check, this will be null
 "macro_help": [{
   "name": "$HOSTADDRESS$",
   "value": "Primary hostname/ip of host",
 }],                        // name/value pairs of macro help. Values will be internationalised
 "plugin_help": "Help information",     // Output from ./check_plugin --help
 "can_change_args": 1,      // 0=cannot change args, 1=can
}

Will return HTTP 400 if:

• service does not exist
• found host, but not the service
• Opsview configuration service check has been removed
• Opsview configuration host has been removed

Parameters:

• hostname & servicename - to identify the service
• args - Optional. Arguments to use to execute. If no TESTCHANGE access, will be ignored and the default used (same as GET args)

Returns:

{
   "command" : "check_snmp_sysinfo -H '127.0.0.1' -t 5 -v '3' -U 'user3' -P XXauthpasswordXX -a \"md5\" -e 'des' -x XXprivpasswordXX",
   "monitored_by" : "master",      // Will not be set if there are no remote collectors
   "return_code" : "0",
   "stderr" : "",
   "stdout" : "Status is OK - SYSTEM: debian7 CONTACT: Joe Bloggs LOCATION: Reading, UK, IN SNMP AGENT: .1.3.6.1.4.1.8072.3.2.10 Linux debian7 3.2.0-4-686-pae #1 SMP Debian 3.2.57-3 i686\n"
}

This REST API lists all the notifications that have been sent by Opsview Monitor.

URL: /rest/notification

METHODS:

• GET - returns rows of notification data
• POST/PUT/DELETE - unimplemented

Parameters:

• rows - number of rows returned, default 50. Can specify "all"
• page - page of data to return. Default 1
• hostgroupid - filters by this host group id. Optional. Can specify multiple times. Will find all hosts from this part of the host group downwards
• hostname - host name to filter notifications on. Optional. Can specify multiple times. Substring search - use % as the wildcard
• servicename - service name to filter on. Optional. Can specify multiple times. Substring search - use % as the wildcard. This will include host objects in the result
• type - 0 = host, 1 = service. Can be specified multiple times. Can use either the key (0) or the value (host). Optional. If not specified, will use both
• order - this parameter is not currently supported. The ordering is by notification time descending
• service_state - filter by service state id or name. Optional. Can be repeated
• host_state - filter by host state id or name. Optional. Can be repeated
• start - start time in epoch seconds. Can use -3600 for 3600 seconds ago. Default -86400 (1 day)
• end - end time in epoch seconds. Default now
• servicesonly - if set, then only return service objects, otherwise will also include the host. Default 0

Limitations:

• If you filter by service name, you will get results for all hosts, whether they have the specified service or not

Example output:

{
 "list": [
   {
     "type": "1",              // 0=host, 1=service
     "name": "opsview::HTTP",  // For a service. Host would be "opsview"
     "time": "1234567890",     // Unix epoch seconds
     "output": "OK - localhost: rta 0.0.29ms lost 0%",

                               // Output for object at time of notification
     "state": "0",             // Possible values for host: 0=up, 1=down, 2=unreachable

                               // For services: 0=ok, 1=warning, 2=critical, 3=unknown
     "notificationtype": "0",  // 0=NORMAL, 1=ACKNOWLEDGEMENT, 2=FLAPPINGSTART, 3=FLAPPINGSTOP, 4=FLAPPINGDISABLED, 5=DOWNTIMESTART, 6=DOWNTIMEEND, 7=DOWNTIMECANCELLED, 8=CUSTOM
     "profiles": [
        {
          "name": "Personal profile",
          "users": [ "alex" ], // This will only be one entry, but in future for BSM, maybe multiple
          "nm": [ "1", "3" ],  // Notification methods used for this notification. See key for the notification methods
        },
        {
          "name": "Some shared notification profile",
          "users": [ "cbalsdon" ],
          "nm": [ "1", "4", "5" ]
        },
        {
          "name": "Some shared notification profile",
                              // This is same as above profile, but cannot be collapsed yet. This may change in future
          "users" : [ "smarsh" , "alex" ],
          "nm" : [ "1", "4", "5" ]
        }
     ]
   }
 ],
 "nms": {      // Key of notification methods
   "1": "com.opsview.notificationmethods.aql",
   "2": "com.opsview.notificationmethods.email",
   "3": "com.opsview.notificationmethods.pagerduty",
   "4": "com.opsview.notificationmethods.smsgateway",
   "5": "custom",
 },
 "summary": {
   "total":"150"  // Total number of records used
 }
}