Opsview Knowledge Center

Suggest Edits

Introduction

Introduction and overview of the Opsview Monitor Rest API

 

Opsview REST API

Opsview has a REST API for updating the Opsview configuration using web service calls on the master 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"
}
  1. For all subsequent requests, add the following headers. Replace the username and tokenstring appropriately:
X-Opsview-Username: username
X-Opsview-Token: tokenstring
  1. 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...") at /usr/local/nagios/perl/lib/Catalyst/Action/Deserialize/JSON.pm line 26, <$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 _/usr/local/nagios/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": "Slave Cluster",
          "ref": "/rest/config/monitoringserver/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 admin' -H "X-Opsview-Token: $token"-X $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: daaf5d130e3cc4ebd9988d56612c2ddd877947e4" -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, /usr/local/nagios/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:

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

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” ]

Server information

URL: /rest/serverinfo

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

Requires RELOADACCESS.

Example returned data:

{
    reload => {
        auditlog_entries     => null,
        average_duration     => "10",
        configuration_status => "pending",
        lastupdated          => "1294852845",
        messages             => [],
        server_status        => "2",
    },
    num_hosts             => "22",
    num_monitoringservers => "3",
    num_nodes             => "4",
    monitoringservers     => [
        {
            name  => "Master Monitoring Server",
            nodes => [
                {
                    status                           => '2',
                    name                             => 'opsview',
                    ip                               => 'opsviewdev46',
                    latency                          => null,
                    max_execution_time               => '4',
                    avg_execution_time               => '3',
                    num_active_service_results_hour  => '85',
                    num_passive_service_results_hour => '509'
                }
            ],
            activated => 1
        },
        {
            name  => "ClusterA",
            nodes => [
                {
                    status                           => '0',
                    name                             => 'opslave',
                    ip                               => 'opslave',
                    latency                          => '0.158',
                    max_execution_time               => '4.3',
                    avg_execution_time               => '3.1',
                    num_active_service_results_hour  => '85',
                    num_passive_service_results_hour => '509'
                }
            ],
            activated => 1
        },
        {
            name  => "Cluster",
            nodes => [
                {
                    status                           => '2',
                    name                             => 'opslaveclusterA',
                    ip                               => 'opslaveclusterAip',
                    latency                          => null,
                    max_execution_time               => '4.3',
                    avg_execution_time               => '3.1',
                    num_active_service_results_hour  => '85',
                    num_passive_service_results_hour => '509'
                },
                {
                    status                           => '3',
                    name                             => 'opslaveclusterB',
                    ip                               => 'opslaveclusterBip',
                    latency                          => null,
                    max_execution_time               => '4.3',
                    avg_execution_time               => '3.1',
                    num_active_service_results_hour  => '85',
                    num_passive_service_results_hour => '509'
                },
                {
                    status                           => '3',
                    name                             => 'opslaveclusterC',
                    ip                               => 'opslaveclusterCip',
                    latency                          => null,
                    max_execution_time               => '4.3',
                    avg_execution_time               => '3.1',
                    num_active_service_results_hour  => null,
                    num_passive_service_results_hour => null
                },
            ],
            activated => 1
        }
    ]
}

The server and slave status values are based on the Nagios plugins status codes.

The configuration_status parameter can take one of the following values:

  • pending - there is at least one change in the Opsview configuration database that requires a reload to make live
  • uptodate - no changes are pending

Note: The master's status value is based on reload→{server_status} value after conversion to a Nagios® Core status. For each slave node, the status is based on the latest status from the master server's Slave-node: check. If a status is not found, a status value of 3 (unknown) is returned.

Note: For each monitoring server's nodes, the latency is the based on the current result of the average active service check latency as returned by the “Nagios Stats” service check. If a value is not available, a null value will be returned.

The reload information is the same as /rest/reload

Logging

All REST failures are logged to /var/log/opsview/opsview-web.log.

This will show a line like:

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

If you want to log all REST requests and responses, uncomment this in /usr/local/opsview-web/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.

Suggest Edits

Rest API Policy

The policy used for maintaining Opsview Monitor Rest APII

 

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

XML Serialisation

Details on the Rest API data format

 

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/monitoringserver/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>
Suggest Edits

Request

General Rest API request types

 

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} (from Opsview 3.11 onwards).

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.

Suggest Edits

Parameters

Available endpoint parameters

 

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
Suggest Edits

Filtering and Searching

Overview of list filtering and searching

 

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 'slave' or FQDN contains 'der', you would have:

....?json_filter={"-or":[{"name":{"-like":"%25slave%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.

Suggest Edits

Ordering

Amending the order of lists

 

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

Suggest Edits

Response

Rest API response format

 

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.

Suggest Edits

Errors

Error you might experience from the Rest API

 

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.

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 /usr/local/nagios/perl/lib/Catalyst/Action/Deserialize/JSON.pm line 26, <$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.

Suggest Edits

Request Format

Config endpoint request details

 

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
}
Suggest Edits

Examples

Some examples for the config endpoints

 

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.

Suggest Edits

Attribute

Rest API Config endpoint for attributes

 

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.

Suggest Edits

Contacts

Rest API Config endpoint for contacts

 

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.

Suggest Edits

Hosts

Rest API Config endpoint for Hosts

 

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/monitoringserver/3",
         "name" : "Cluster"
      },
      "alias" : "Host to be monitored by slave",
      "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 server; is_ms=1 if this host is used as a monitoring server (master or slave); is_netflow=1 if this host is used as a NetFlow source. Note that the 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.

Suggest Edits

Test Service Check

Endpoint to test a Service Check on a Host

 

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 master monitoring server.
  • 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.

Suggest Edits

Host Check Command

Rest API Config endpoint for host check commands

 

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.

Suggest Edits

Host Group

Rest API Config endpoint for host groups

 

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.

Suggest Edits

Host Icons

Rest API Config endpoint for host icons

 

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
  },
}
Suggest Edits

Host Templates

Rest API Config endpoint for host templates

 

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
Suggest Edits

Keyword/Hashtag

Rest API Config endpoint for hashtags (previously known as keywords)

 

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

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"
   }
}
Suggest Edits

Monitoring Servers

Rest API Config endpoint for monitoring servers

 

Object type: monitoringserver

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_by_slave"
         }
      ],
      "name" : "ClusterA",
      "nodes" : [
         {
            "host" : {
               "ip" : "192.168.10.20",
               "ref" : "/rest/config/host/5",
               "name" : "opslave"
            },
            "slave_port" : "22"
         }
      ],
      "id" : "2",
      "uncommitted" : "1"
   }
}

If id=1, this is the master monitoring server.

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

Additional parameters:

  • order - can be num_hosts or num_nodes to order the list of monitoring servers by those columns.
  • include_delete_info - if set, will return extra fields indicating if a monitoring server is not deletable because it is the master, it is used as a netflow collector, it still has hosts associated to it, or if the monitoring server 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 limitation):

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

When PUT/POSTing to monitoringservers, 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. For the master monitoring server, only the first node is used and the remainder silently ignored.

Suggest Edits

NetFlow Collectors

Rest API Config endpoint for netflow collectors (NetAudit module users only)

 

Object type: netflow_collector

Example GET all

Request URL:/rest/config/netflow_collector

Response:

{
   "list" : [
      {
         "id" : "1",
         "monitoringserver_id" : "1",
         "name" : "Master server collector",
         "ref" : "/rest/config/netflowcollector/1",
         "uncommitted" : "0"
      },
      {
         "id" : "2",
         "monitoringserver_id" : "3",
         "name" : "Slave collector",
         "ref" : "/rest/config/netflowcollector/2",
         "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",
      "monitoringserver_id" : "1",
      "name" : "Master server collector",
      "uncommitted" : "0"
   }
}

Example PUT

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

Request URL:/rest/config/netflow_collector/1

Request data:

{
   "object" : {
      "id" : "1",
      "monitoringserver_id" : "1",
      "name" : "A new name",
   }
}

Response:

{
   "object" : {
      "id" : "1",
      "monitoringserver_id" : "1",
      "name" : "A new name",
      "uncommitted" : "1"
   }
}

Example POST

Request URL:/rest/config/netflow_collector

Request data:

{
   "object" : {
      "monitoringserver_id" : "2",
      "name" : "Second collector",
   }
}

Response:

{
   "object" : {
      "id" : "3",
      "monitoringserver_id" : "2",
      "name" : "Second collector",
      "uncommitted" : "1"
   }
}

Example DELETE

Request URL:/rest/config/netflow_collector/2

Response:

{
   "success" : "1"
}
Suggest Edits

NetFlow Sources

Rest API Config endpoint for netflow sources (NetAudit module users only)

 

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"
}
Suggest Edits

Notification Method

Rest API Config endpoint for notification methods

 

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" },
     ]
    
Suggest Edits

Roles

Rest API Config endpoint for roles

 

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.

Suggest Edits

Service Checks

Rest API Config endpoint for service checks

 

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: In Opsview prior to 3.11.0, the snmp trap rule objects were returning an id field - this is incorrect as it may not be possible to push the resultant data back into Opsview. This field should be removed before attempting to PUT or POST.

Suggest Edits

Service Group

Rest API Config endpoint for service groups

 

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.

Suggest Edits

Shared Notification Profiles

Rest API Config endpoint for shared notification profiles

 

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"
   {
{
Suggest Edits

Tenancy

Rest API Config endpoint for tenancies

 

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"
}
Suggest Edits

Time Period

Rest API Config endpoint for time periods

 

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_slave"
         }
      ],
      "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.

Suggest Edits

Plugin

Details about managing plugins via the Rest API

 

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 slave, 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 }
Suggest Edits

Request Format

Downtime endpoint request details

 

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 or DOWNTIMEALL access.

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

Note: You can only set downtime at the host group level with DOWNTIMEALL.
Note: If a user has access to some, but not all, services on a host and sets downtime for the host, then all services will also be marked in downtime. This means it is possible that a downtime has been set on a service by a user that does not have view access for.
Note: If a user has DOWNTIMEALL, but only VIEWSOME, the user could set downtime for objects that they cannot view.

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 objects in Nagios® Core - hosts or services. Use the filter parameters below when POSTing to the REST API. There are different filtering parameters for GET requests.
When setting downtime in the REST API, we can set downtime against a host group, a host or a service. You can specify these objects through URL parameters. Note that although you can specify downtime for a host group, it is stored in Nagios Core as downtime for each host and its services.
You can choose hosts or services using the same URL parameters as the status API, with 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. In addition, setting or deleting downtime for host groups requires DOWNTIMEALL access.
The basic rule is that if you are searching for multiple fields of the same type of object, then the search fields are AND'd together, but multiple values of the same field are OR'd together.
Duplicated host or services are ignored. Duplicate host groups are also ignored, but as downtime is set against leaf host groups, it is possible to set the downtime twice on the same host groups.
If you request a specific object (using hg.hostgroupid, hg.hostgroupname, hst.hostname, hst.hostid, svc.hs, svc.serviceid) and that object does not exist, an error is raised:

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

Suggest Edits

Listing

Endpoint to list existing downtimes

 

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.

Suggest Edits

Creating

Endpoint to create downtimes on hosts and services

 

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

/usr/local/nagios/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>'”
Suggest Edits

Deleting

Endpoint to delete downtimes from hosts and services

 

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

Request Format

Config endpoint request details

 

Security level required:

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

Host Group Summary

Rest API status endpoint for Host Group summary

 

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.

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.

Suggest Edits

Host Summary

Endpoint for Host summary information

 

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=opslave&host=opsview:

{
   "list" : [
      {
         "alias" : "Slave",
         "current_check_attempt" : "0",
         "downtime" : "0",
         "icon" : "opsview",
         "last_check" : "0",
         "max_check_attempts" : "0",
         "name" : "opslave",
         "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
Suggest Edits

Service List

Endpoint for Servicecheck status information

 

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 - default 0. If set, will return hosts in the response as well as services. Also, it will change the filter=unhandled/handled to include hosts. Note: if set, each host could have 'services: []', which means this is a host only object. Note: this parameter can change the definition of ordering by state and host_state
  • 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.
  • 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" : "Slave-node: opslave",
               "output" : "slave-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" : "Slave-node: opslaveclusterA",
               "output" : "slave-node opslaveclusterA 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.

Suggest Edits

Filtering Service Objects

Filtering Servicecheck status details

 

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

Set Service Status

Endpoint for setting the status of a Servicecheck on a Host

 

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"
         }
      ]
   }
}
Suggest Edits

Hashtags Summary

Endpoint for summary of Hashtags information

 

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

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.

Suggest Edits

Hashtags Detail

Endpoint for detailed Hashtags information

 

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.

Suggest Edits

Performance Metrics

Performance Metrics Rest API endpoint

 

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": "opslave",
        "metricname": "age",
        "servicename": "Nagios Stats",
        "servicestate": "critical",
        "uom": "s",
        "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

Suggest Edits

Host and Services

Rest API endpoint for current host and service status from the Runtime database

 

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"
}
Suggest Edits

Performance Metrics

Rest API endpoint for current host and service metrics from the Runtime database

 

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.

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" : [
      "opslave::/::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"
}
Suggest Edits

Monitoring Servers

Rest API endpoint for current monitoring servers from the Runtime database

 

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/monitoringserver. Requires authentication - requires VIEWALL or VIEWSOME permission.

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

Access Control

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

Retrieving Monitoring Servers

Parameters:

  • include_hosts - if set to 1, will include all hosts monitored by this monitoring server.

Response:

  • list - an array of the results

The list will be an associative array of:

  • id - id number of the monitoring server. id=1 means it is the master server.
  • name - name of the monitoring server
  • nodes - this will be a list of the nodes by host name
  • hosts - if include_hosts=1, this will be a list of hosts by name
  • activated - either 0 or 1
  • passive - either 0 or 1

Example response:

{
   "allrows" : "3",
   "list":[{
     "id":1,
     "name":"Master Monitoring Server",
     "nodes":[{
      'name':'opsview",
     }],
     "hosts":[
       {"name":"opsviewdev46"},
       {"name":"cisco1"}
     ],
     "activated":"1",
     "passive":"0",
    },
    {
     "id":2,
     name:"ClusterA",
     hosts:[],
     nodes:[{
      'name':'opslave',
     }],
     "activated":"1",
     "passive":"0",
    },
    {
     "id":3,
     "name":"Cluster",
     "hosts":[
       {"name":"cisco2"},
       {"name":"cisco3"}
     ],
     "nodes":[
     {
      'name':'opslaveclusterA',
     },
     {
      'name':'opslaveclusterB',
     },
     {
      'name':'opslaveclusterC',
     },
     ],
     activated:1
    }
   ]
   "rows" : "3",
}
Suggest Edits

Network Topology Map

Rest API endpoint for current network toplogy from the Runtime database

 

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_slave", "cisco4" ]
        },
        {
            name: "cisco4",
            parents: [ "cisco" ],
            children: [ null ]
        }
    ]
}
Suggest Edits

Host Templates

Rest API endpoint for current Host Templates from the Runtime database

 

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,
}
Suggest Edits

Request Format

Acknowledge endpoint request details

 

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, DELETE - not implemented

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 objects in Nagios® Core - hosts or 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:

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

Suggest Edits

Listing

Endpoint for listing unhandled hosts and services

 

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.

Suggest Edits

Setting

Endpoint for acknowledging a host or service issue

 

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

Request Format

Description for Service Check rechecking Rest API endpoint

 

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

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.

Suggest Edits

Listing

Endpoint for listing available Service Checks and Hosts

 

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.

Suggest Edits

Requesting

How to request a recheck of a Service Check or Host via the Rest API

 

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"
Suggest Edits

Request Format

Endpoint access details for the Rest API graph URI

 

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

Listing

Endpoint to list graphing data

 

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.

Suggest Edits

Request Format

Endpoint for requesting details about Events

 

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.

Suggest Edits

Request Format

Details about the Notes endpoint

 

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&amp;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
Suggest Edits

Setting

Adding a Note to an object via the Rest API

 

Input:

/usr/local/nagios/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:

{
/usr/local/nagios/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"
}
}

Suggest Edits

Request Format

Details for using the 'queryhost' endpoint

 

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.

Suggest Edits

Listing

Details about using the queryhost endpoint to list interfaces

 

Valid parameters are:

  • ip - Hostname or IP address. Required.
  • snmp_version - one of 1, 2c or 3. Required.
  • hostid - hostid of the host from the DB. Not required if this is a new host.
  • msid - the monitoring server that the query is to be run from. Will use the first node if it is a cluster. Can be set to the master. Default is master.
  • 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",
}
Suggest Edits

Request Format

Endpoint request information for 'detail'

 

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

Methods:

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

Listing

Using the detail endpoint to retrieve information

 

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": "Slave",            // Name of monitoring server. Could be null if monitoring server deleted. Uses the runtime tables
  "check_type": 1,                    // Options: 1 = Active Plugin, 2 = Passive, 4 = SNMP Trap, 5 = SNMP Polling. Could be null to be unknown
  "latency": 0.000,                   // could be null if from slave - do not display
  "duration": 0.003,                  // could be null if from slave - do not display
  "next_check_expected": 1234567890,  // epoch seconds. If 0, not known
  "last_state_change": 1234567890,    // epoch seconds
  "last_notification": 1234567890,    // epoch seconds. Could be null
  "notification_number": 0,           // Number
  "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. If this host is monitored_by a slave, then this will always be 0
  "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
 }
}
Suggest Edits

Setting

Setting Host or Servicecheck states

 

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 Nagios
  "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
 }
}
Suggest Edits

Request Format

How to run tests against an active service check plugin

 

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
Suggest Edits

Listing

How to identify specific service checks

 

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 slaves
   "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"
}
Suggest Edits

Request Format

Format for the endpoint to list notifications

 

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
Suggest Edits

Listing

Endpoint to return notification information

 

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 - valid options: time_desc (default)

    • 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" ], // For Nagios notifications, 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 due to Nagios limitations. 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
 }
}