Rest API Config endpoint for Hosts
Object type: host
Request URL: /rest/config/host
Example GET response:
{
"object" : {
"snmpv3_privprotocol" : null,
"flap_detection_enabled" : "1",
"hosttemplates" : [
{
"ref" : "/rest/config/hosttemplate/4",
"name" : "Blank"
}
],
"keywords" : [],
"check_period" : {
"ref" : "/rest/config/timeperiod/3",
"name" : "nonworkhours"
},
"hostattributes" : [
{
"arg1" : null,
"arg2" : null,
"arg3" : null,
"arg4" : null,
"value" : "/remote",
"name" : "DISK"
},
{
"arg1" : null,
"arg2" : null,
"arg3" : null,
"arg4" : null,
"value" : "opsviewd",
"name" : "PROCESS"
}
],
"id" : "22",
"notification_period" : {
"ref" : "/rest/config/timeperiod/1",
"name" : "24x7"
},
"notification_options" : "d,r",
"name" : "monitored_by_cluster",
"rancid_vendor" : null,
"hostgroup" : {
"ref" : "/rest/config/hostgroup/5",
"name" : "Leaf2"
},
"enable_snmp" : "1",
"event_handler" : "",
"monitored_by" : {
"ref" : "/rest/config/monitoringcluster/3",
"name" : "Cluster"
},
"alias" : "Host to be monitored by collector",
"uncommitted" : "1",
"parents" : [],
"retry_check_interval" : "4",
"icon" : {
"name" : "SYMBOL - Wireless network",
"path" : "/images/logos/wireless_small.png"
},
"ip" : "monitored_by_clusterip",
"use_mrtg" : "0",
"servicechecks" : [
{
"ref" : "/rest/config/servicecheck/45",
"name" : "Check Loadavg",
"exception":"-w 5,5,5 -c 9,9,9",
"timed_exception":null,
"event_handler":null,
"remove_servicecheck":0,
},
{
"ref" : "/rest/config/servicecheck/4",
"name" : "DNS",
"exception":"--other --args",
"timed_exception":null,
"event_handler":null,
"remove_servicecheck":1,
},
{
"ref" : "/rest/config/servicecheck/6",
"name" : "HTTP",
"timed_exception":{
"timeperiod" : { "name" : "workhours" },
"args" : "--url=/about -w 2 -c 4",
},
"exception":null,
"remove_servicecheck":0,
"event_hander":"restart_http",
],
"use_rancid" : "0",
"nmis_node_type" : "server",
"snmp_version" : "2c",
"use_nmis" : "1",
"rancid_connection_type" : "ssh",
"snmpv3_authprotocol" : null,
"rancid_username" : null,
"rancid_password" : null,
"check_command" : {
"ref" : "/rest/config/hostcheckcommand/7",
"name" : "NRPE (on port 5666)"
},
"check_attempts" : "15",
"check_interval" : "25",
"notification_interval" : "60",
"snmpv3_privpassword" : "",
"snmpv3_username" : "",
"other_addresses" : "",
"business_components" : []
}
}
Example
To create a new host called newhost where the name can be looked up in DNS. Note: this server will not be seen after an 'apply changes' as no servicechecks have been applied.
$ opsview_rest --username=admin --password=initial --pretty --data-format=json POST 'config/host' --data '{"name":"newhost"}'
{
"object" : {
"alias" : "",
"business_components" : [],
"check_attempts" : "2",
"check_command" : null,
"check_interval" : "300",
"check_period" : {
"name" : "24x7",
"ref" : "/rest/config/timeperiod/1"
},
"enable_snmp" : "0",
"event_handler" : "",
"event_handler_always_exec" : "0",
"flap_detection_enabled" : "1",
"hostattributes" : [],
"hostgroup" : {
"name" : "Build System",
"ref" : "/rest/config/hostgroup/5"
},
"hosttemplates" : [],
"icon" : {
"name" : "LOGO - Opsview",
"path" : "/static/images/logos/opsview.png"
},
"id" : "38",
"ip" : "newhost",
"keywords" : [],
"last_updated" : "1606481281",
"monitored_by" : {
"name" : "Master Monitoring Server",
"ref" : "/rest/config/monitoringcluster/1"
},
"name" : "newhost",
"notification_options" : null,
"notification_period" : {
"name" : "24x7",
"ref" : "/rest/config/timeperiod/1"
},
"other_addresses" : "",
"parents" : [],
"rancid_autoenable" : "0",
"rancid_connection_type" : "ssh",
"rancid_username" : null,
"rancid_vendor" : null,
"retry_check_interval" : "60",
"servicechecks" : [],
"snmp_extended_throughput_data" : "0",
"snmp_max_msg_size" : "0",
"snmp_port" : "161",
"snmp_use_getnext" : "0",
"snmp_use_ifname" : "0",
"snmp_version" : "2c",
"snmpv3_authprotocol" : null,
"snmpv3_privprotocol" : null,
"snmpv3_username" : "",
"tidy_ifdescr_level" : "0",
"uncommitted" : "1",
"use_rancid" : "0"
}
}
Example PUT to update the above host and replace the Hosttemplates list:
$ opsview_rest --username=admin --password=initial --pretty --data-format=json PUT 'config/host' --data '{"name":"newhost", "hosttemplates": [ { "name":"Network - Base" } ] }'
{
"object" : {
...
"hosttemplates" : [
{
"name" : "Network - Base",
"ref" : "/rest/config/hosttemplate/194"
}
],
...
}
}
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=1if this host is used as the master/primary server;is_ms=1if this host is used as a collector (from Opsview 6) or monitoring server (master or slave, in Opsview 5 and below);is_netflow=1if this host is used as a NetFlow source. Note that id must be one of the columns returned to identify the monitoring server. - include_encrypted=1 — If set, Opsview will return the SNMP community, SNMPv3 authentication password, or SNMPv3 privacy password as encrypted_snmp_community, encrypted_snmpv3_authpassword and encrypted_snmpv3_privpassword respectively. This could return the empty string to mean no password is set.
There are additional options for filtering by related objects:
- s.hosttemplates.name - will search for hosts that have this host template. If this parameter is repeated, will list all hosts that have any of these host templates. If you want to find hosts that have all of the host templates, you need to include the
c.hosttemplates.name=allparameter. - s.hosttemplates.id - same as above, searching host templates by id.
c.hosttemplates.id=allwill 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=allto 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: For host attributes, if an arg is set to be encrypted for this particular attribute, the value will not exist in the GET request.
Note: Errors will be thrown if validation fails for check_interval, retry_check_interval or check_attempts
Note: When the system option Change Log is enabled you must include "changelog":"Description of the change" within the payload to successfully POST the change
Note: When setting the snmpv3_privprotocol object field, the ‘aes256’ and ‘aes256c’ options are only fully supported on some operating systems, in Opsview 6.6.7 and above (see SNMP Privacy Protocol Support).
SNMP Interfaces
As mentioned above, the snmpinterfaces for all hosts, or any individual hosts, can be requested by adding it into the cols list:
/rest/config/host?rows=all&cols=%2Bsnmpinterfaces
/rest/config/host?s.name=myhost01&cols=%2Bsnmpinterfaces
Note: the %2B used here is the URL encoded value for + which some clients need.
This will include extra information in the output:
$ opsview_rest --username=admin --password=initial --pretty --data-format=json GET 'config/host?s.name=SNMP_v2&cols=%2Bsnmpinterfaces'
{
"list" : [
{
....
"enable_snmp" : "1",
....
"name" : "SNMP_v2",
....
"snmp_extended_throughput_data" : "0",
"snmp_max_msg_size" : "0",
"snmp_port" : "161",
"snmp_use_getnext" : "0",
"snmp_use_ifname" : "0",
"snmp_version" : "2c",
"snmpinterfaces" : [
{
"active" : "0",
"discards_critical" : "15",
"discards_warning" : null,
"duplicatename" : "0",
"errors_critical" : "10",
"errors_warning" : null,
"indexid" : "0",
"interfacename" : "",
"throughput_critical" : "50%",
"throughput_warning" : null
},
{
"active" : "0",
"discards_critical" : "",
"discards_warning" : "",
"duplicatename" : "0",
"errors_critical" : "",
"errors_warning" : "",
"indexid" : "0",
"interfacename" : "eth0",
"throughput_critical" : "",
"throughput_warning" : ""
},
],
"snmpv3_authprotocol" : null,
"snmpv3_privprotocol" : null,
"snmpv3_username" : "",
"tidy_ifdescr_level" : "0",
"uncommitted" : "0",
"use_rancid" : "0"
}
],
....
}
The first entry (with active=0 and no interfacename) is the default monitoring settings used for all interfaces on this host (the standard settings are shown above). This row MUST be included when submitting the list of interfaces back to the server.
For the interface to be monitored, active must be set to 1.
Instead of manually building up the entries, you can request a Query Host scan to fetch the information from the device using the SNMP settings configured for the host which you can then POST back using this endpoint. See the Query Host API section for more details.