Config - Hosts

Object type: host

Request URL: /rest/config/host

Example GET response Copied

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.

Example PUT Copied

To update the above host and replace the hosttemplates list:

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 service checks 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:

Note

The %2B used here is the URL encoded value for + which some clients need.

This will include extra information in the output:

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. For more information, see the Query Host API section.

Changing SNMP credentials in bulk Copied

When managing a large number of devices, you can perform bulk changes to SNMP version settings.

1. Export the values for the hosts you want to modify. You can query a single host, multiple hosts, or apply filters to retrieve a group of hosts.

• Single host:

• Multiple hosts:

This creates a file named snmp_network_hosts.json located in the /tmp/ directory. Verify that the file was successfully generated.

To retrieve hosts by host template or host group using a filter, refer to the Alternative filters section.

2. Generate encrypted values by running the following command:

3. In the snmp_network_hosts.json file, edit the relevant fields using encrypted credentials and SNMPv3 parameters. After entering the SNMPv3 password, an encrypted value will be provided. Modify the .json file with the correct fields for SNMPv3 credentials.

4. Update the configuration using the following command:

5. Apply the configuration changes in the Opsview UI using Apply Changes, or send an API request to Opsview to reload its configuration:

6. Test to confirm that the host is using the correct SNMPv3 credentials.

Alternative filters Copied

You can apply alternative filters to retrieve all hosts within a specific host template or host group. The following are example commands for filters:

Host groups Copied

Host templates Copied

Note

Test the filter with a single host first to ensure that you get the expected results.