Welcome to docs.opsview.com

REST API: Config

This handles all the REST API end points regarding the configuration database for Opsview.

The end points are of the form: /rest/config/{objecttype}.

All examples here are in JSON, although XML can also be used.

Request

Allowed Verbs
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} 1)

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

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

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

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

Response

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.

Single object

The response format for a single object is:

{
    "object": {...}
}

List

The response format for a list of items is:

{
    "list": [
        {...},
        {...},
        {...}
    ],
    "summary": {
        "allrows": "153",  // The count of all rows for this data type (restricted by user access, eg. hosts).
        "page": 1,         // Current page number.
        "rows": "30",      // Number of rows in the response, or "allrows".
        "totalpages": 4,   // Based on the pages and the number of rows per page, this is the total number of pages.
        "totalrows": "100" // Total number of rows based on the search parameters.
    }
}

The object hash is the same as a single object.

The value for the ref key provides a way of accessing the related object. Note: some of the ref links are not provided yet - this will be detailed in the documentation for each object type.

URL parameters that can be used on list page
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.

Order

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

JSON filter

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.

Errors

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.

Interface

General configuration data

These are the general URLs for each object type.

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 (available from Opsview 3.10.1)

If an error occurs, the behaviour is different based on the version of Opsview.

Opsview 3.10.1 or above

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:

{
    "detail": "Detail about the error",
    "message": "Rollback. Error trying to synchronise object: 2",
    "objects_updated": 0
}
Opsview 3.10.0 or 3.9.1 or earlier

Objects up to the failure point will have been committed to the system. No further objects will be attempted in the list. The data returned will be of the format:

{
    "detail": "more information",
    "message": "Error trying to synchronise object: 2",
    "objects_updated": 1
}

You can use the “objects_updated” value to remove items in the list before re-attempting the request again.

Object types

Contact

Object type: contact

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

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

Host

Object type: host

Example GET
Request URL /rest/config/host/22
Response
{
    "object": {
        "alias": "Host to be monitored by slave",
        "business_components": [],
        "check_attempts": "15",
        "check_command": {
            "name": "NRPE (on port 5666)",
            "ref": "/rest/config/hostcheckcommand/7"
        },
        "check_interval": "25",
        "check_period": {
            "name": "nonworkhours",
            "ref": "/rest/config/timeperiod/3"
        },
        "enable_snmp": "1",
        "event_handler": "",
        "flap_detection_enabled": "1",
        "hostattributes": [
            {
                "arg1": null,
                "arg2": null,
                "arg3": null,
                "arg4": null,
                "name": "DISK",
                "value": "/remote"
            },
            {
                "arg1": null,
                "arg2": null,
                "arg3": null,
                "arg4": null,
                "name": "PROCESS",
                "value": "opsviewd"
            }
        ],
        "hostgroup": {
            "name": "Leaf2",
            "ref": "/rest/config/hostgroup/5"
        },
        "hosttemplates": [
            {
                "name": "Blank",
                "ref": "/rest/config/hosttemplate/4"
            }
        ],
        "icon": {
            "name": "SYMBOL - Wireless network",
            "path": "/images/logos/wireless_small.png"
        },
        "id": "22",
        "ip": "monitored_by_clusterip",
        "keywords": [],
        "monitored_by": {
            "name": "Cluster",
            "ref": "/rest/config/monitoringserver/3"
        },
        "name": "monitored_by_cluster",
        "nmis_node_type": "server",
        "notification_interval": "60",
        "notification_options": "d,r",
        "notification_period": {
            "name": "24x7",
            "ref": "/rest/config/timeperiod/1"
        },
        "other_addresses": "",
        "parents": [],
        "rancid_connection_type": "ssh",
        "rancid_password": null,
        "rancid_username": null,
        "rancid_vendor": null,
        "retry_check_interval": "4",
        "servicechecks": [
            {
                "event_handler": null,
                "exception": "-w 5,5,5 -c 9,9,9",
                "name": "Check Loadavg",
                "ref": "/rest/config/servicecheck/45",
                "remove_servicecheck": 0,
                "timed_exception": null
            },
            {
                "event_handler": null,
                "exception": "--other --args",
                "name": "DNS",
                "ref": "/rest/config/servicecheck/4",
                "remove_servicecheck": 1,
                "timed_exception": null
            },
            {
                "event_hander": "restart_http",
                "exception": null,
                "name": "HTTP",
                "ref": "/rest/config/servicecheck/6",
                "remove_servicecheck": 0,
                "timed_exception": {
                    "args": "--url=/about -w 2 -c 4",
                    "timeperiod": {
                        "name": "workhours"
                    }
                }
            }
        ],
        "snmp_version": "2c",
        "snmpv3_authprotocol": null,
        "snmpv3_privpassword": "",
        "snmpv3_privprotocol": null,
        "snmpv3_username": "",
        "uncommitted": "1",
        "use_mrtg": "0",
        "use_nmis": "1",
        "use_rancid": "0"
    }
}
Optional Parameters
is_parent=1 List only hosts that are parents.
include_ms=1 Adds 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.
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 (require a cols=+snmpinterfaces or cols=%2Bsnmpinterfaces to force these to be listed):

  • snmpinterfaces - this returns the list of interfaces associated with the 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.

Test Service Check

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.

Example GET
Request URL /rest/config/host/testservicecheck
Response
{
    "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"
}
Input URL parameters
scid Service check ID number. Required.
args 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 ID of the monitoring server to run the test service check from. If not specified, will use the master monitoring server.
hostid 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
ip
hostname
other_addresses

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

Role

Object type: role

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

A parameter of “order=priority” will list the roles in the same order that the web page displays them. 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.

Service Check

Object type: servicecheck

Example GET
Request URL /rest/config/servicecheck/79
Response
{
    "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 POST/PUT the resultant data back into Opsview. This field should be removed before attempting to PUT or POST.

Host Template

Object type: hosttemplate

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

Notes on attributes:

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

Attribute

Object type: attribute

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

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-4 and value are available from Opsview 3.11.0.

Time Period

Object type: timeperiod

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

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.

Host Group

Object type: hostgroup

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

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

The parent contains a 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 is 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.

Service group

Object type: servicegroup

Example GET
Request URL /rest/config/servicegroup/2
Response
{
    "object": {
        "id": "2",
        "name": "Application - web server",
        "servicechecks": [
            {
                "name": "HTTP",
                "ref": "/rest/config/servicecheck/85"
            }
        ],
        "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.

Notification Method

Object type: notificationmethod

Example GET
Request URL /rest/config/notificationmethod/1
Response
{
    "object": {
        "active": "1",
        "command": "submit_sms_aql -u '' -p '' -P ''",
        "contact_variables": "PAGER",
        "id": "1",
        "master": "0",
        "name": "AQL",
        "namespace": "com.opsview.notificationmethods.aql",
        "notificationprofiles": [
            {
                "name": "Non work hours sms",
                "ref": "/rest/config/notificationprofile/12"
            },
            {
                "name": "Default",
                "ref": "/rest/config/notificationprofile/3"
            }
        ],
        "uncommitted": "0",
        "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" },
],

Host Check Command

Object type: hostcheckcommand

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

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

Keyword

Object type: keyword

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

Shared Notification Profile

Object type: sharednotificationprofile

Example GET
Request URL /rest/config/sharednotificationprofile/3
Response
{
    "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"
    }
}

Monitoring Server

Object type: monitoringserver

Example GET
Request URL /rest/config/monitoringserver/2
Response
{
    "object": {
        "activated": "1",
        "id": "2",
        "monitors": [
            {
                "name": "cisco3",
                "ref": "/rest/config/host/10"
            },
            {
                "name": "monitored_by_slave",
                "ref": "/rest/config/host/4"
            }
        ],
        "name": "ClusterA",
        "nodes": [
            {
                "host": {
                    "ip": "192.168.10.20",
                    "name": "opslave",
                    "ref": "/rest/config/host/5"
                },
                "slave_port": "22"
            }
        ],
        "roles": [
            {
                "name": "View some, change some",
                "ref": "/rest/config/role/12"
            }
        ],
        "uncommitted": "1"
    }
}
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.

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.

There is an activated_calculated column that will be included if “order=activated_calculated” is set. This can be one of four 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.

NetFlow Collector

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

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

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

NetFlow Source

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

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

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

Tenancy

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 GET
Request URL /rest/config/tenancy/2
Response
{
    "success": "1"
}

Host Icon

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

Examples

Updating multiple service checks

The REST API can be used to update multiple service checks in one go:

  1. Obtain the list of check to be modified and store in a file. Eg., 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
    
  2. Edit the checks.json file as necessary
  3. 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, otherwise 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.

1) from Opsview 3.11 onwards
Navigation
Print/export
Toolbox