ITRS Opsview Cloud Documentation

Common Examples

opsview_rest Copied

opsview_rest is a tool provided to make using the Opsview API easier.

While you can run opsview_rest with username/password credentials, it is recommended that you use it to first generate a REST API token and then call all subsequent requests using it.

To generate the token and save it at /path/to/opsview_restapi_token:

opsview_rest --username admin --password initial --token-file /path/to/opsview_restapi_token GET info

Thereafter, the username and password do not need to be supplied:

opsview_rest --token-file /path/to/opsview_restapi_token GET info

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

opsview_rest --token-file /path/to/opsview_restapi_token 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 --token-file /path/to/opsview_restapi_token --data-format=json --pretty GET config/host/1

You can get the output to edit and put back again:

opsview_rest --token-file /path/to/opsview_restapi_token --data-format=json --pretty GET config/host/1 > host.json
vim host.json
opsview_rest --token-file /path/to/opsview_restapi_token --content-file=host.json --data-format=json --pretty PUT config/host/1

To show all performance statistics for the “Unix Swap” metric:

opsview_rest --token-file /path/to/opsview_restapi_token --pretty GET '/rest/status/performancemetric/?servicename=Unix Swap'

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

opsview_rest --token-file /path/to/opsview_restapi_token --pretty GET /rest/status/performancemetric/?hostname=opsview

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

opsview_rest --token-file /path/to/opsview_restapi_token --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": ""

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

opsview_rest --token-file /path/to/opsview_restapi_token --pretty --data-format=json --content-file=/path/to/newhost.json PUT config/host

To delete a host via its ID:

opsview_rest --token-file /path/to/opsview_restapi_token --pretty DELETE config/host/<ID>

To perform a reload of Opsview:

opsview_rest --token-file /path/to/opsview_restapi_token --pretty POST reload

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

Unix tools Copied

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


The text and 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 Copied

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.


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 Copied

The REST API is separated into different sections:

["Opsview On-premises"] ["API", "Technical Reference"]

Was this topic helpful?