Common Examples

opsview_rest

  • You can use /opt/opsview/coreutils/bin/opsview_rest to communicate with the REST API on the Orchestrator. 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.

opsview_rest --username=admin --password=initial --data-format=json --pretty GET config/host/1
  • You can get the output to edit and put back again:
opsview_rest --username=admin --password=initial --data-format=json --pretty GET config/host/1 > host.json
vim host.json
opsview_rest --username=admin --password=initial --content-file=host.json --data-format=json --pretty PUT config/host/1
  • To show all performance statistics for the “unix swap” metric:
opsview_rest --username=admin --password=initial --pretty GET '/rest/status/performancemetric/?servicename=Unix Swap'
  • To show all performance statistics for the host, “opsview”:
opsview_rest --username=admin --password=initial --pretty GET /rest/status/performancemetric/?hostname=opsview
  • To show the “load average” metric from host, “opsview”:
opsview_rest --username=admin --password=initial --pretty GET '/rest/status/performancemetric?order=metricname&order=hostname&metricname=load1&hostname=opsview'
  • To add a host, you need to create a JSON file with the information — you can perform a GET on an existing host to see the template. Eg.,
{
    "hostgroup": {
        "name": "Production"
    },
    "hosttemplates": [
        {
            "name": "OS - Linux Advanced"
        }
    ],
    "icon": {
        "name": "LOGO - Opsview",
        "path": "/images/logos/opsview_small.png"
    },
    "ip": "newhost.fqdn",
    "monitored_by": {
        "name": "Collector Cluster",
        "ref": "/rest/config/monitoringcluster/3"
    },
    "name": "newhost",
    "other_addresses": "192.168.12.1"
}

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

opsview_rest --user=admin --password=initial --pretty --data-format=json --content-file=/path/to/newhost.json PUT config/host
  • To delete a host via its ID:
opsview_rest --username=admin --password=initial --pretty DELETE config/host/<ID>
  • To perform a reload of Opsview:
opsview_rest --username=admin --password=initial --pretty POST reload
  • opsview_rest can also make use of an authentication token. To create the token file the first login must use a password:
opsview_rest -u admin -p initial -t /path/to/opsview_restapi_token GET info

Thereafter, the password does not need to be supplied:

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

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

Unix tools

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

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

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

token=`jq -r .token logindata`

You can then use $token:

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

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

To list out the first record in the response:

jq '.list[0]' eventdata

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

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

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

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

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

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

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

export_host_template

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

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

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

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

Interface

The REST API is separated into different sections:

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

Other common endpoints are listed below.