Config - Hosts

Object type: host

Request URL: /rest/config/host

Example GET response Copied

    {
       "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 Copied

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 Copied

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=1 if this host is used as the master/primary server; is_ms=1 if this host is used as a collector (from Opsview 6) or monitoring server (master or slave, in Opsview 5 and below); is_netflow=1 if 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=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.

Take note of the following considerations:

When applying a timed exception, if the related timeperiod is not found, the timed exception is silently dropped.
For host attributes, if an arg is set to be encrypted for this particular attribute, the value will not exist in the GET request.
Errors will be thrown if validation fails for check_interval, retry_check_interval or check_attempts
When the system option Change Log is enabled you must include "changelog":"Description of the change" within the payload to successfully POST the change
When setting the snmpv3_privprotocol object field, the ‘aes256’ and ‘aes256c’ options are only fully supported on some operating systems (see SNMP Privacy Protocol Support).

SNMP interfaces Copied

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",
               "alert_type" : "normal",
               "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",
               "alert_type" : "normal",
               "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.

Previous article Next article

Config - Hosts

Example GET response Copied

Example Copied

Example PUT Copied

SNMP interfaces Copied

Was this topic helpful?

Your thoughts...

How can we improve this topic?

Your thoughts...

Thank you for your feedback!