---
title: "Config - Hosts"
description: ""
url: "https://docs.itrsgroup.com/docs/opsview/6.11.7/rest-api/config/api-config-hosts/index.html"
---
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](https://docs.itrsgroup.com/docs/opsview/6.11.7/configuration/apply-changes/index.html) as no servicechecks have been applied.



```
$ opsview_rest --token-file /path/to/opsview_restapi_token --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 --token-file /path/to/opsview_restapi_token --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 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](https://docs.itrsgroup.com/docs/opsview/6.11.7/prerequisites/snmp-requirements/index.html#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 --token-file /path/to/opsview_restapi_token --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. For more information, see the [Query Host](https://docs.itrsgroup.com/docs/opsview/6.11.7/rest-api/queryhost/api-queryhost-request-format/index.html) API section.

## Changing SNMP credentials in bulk

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:

```
opsview_rest --token-file /path/to/opsview_restapi_token --pretty --data-format=json GET /rest/config/host"?include_encrypted=1&s.name=<hostaname>" > /tmp/snmp_network_hosts.json
```

- Multiple hosts:

```
opsview_rest --token-file /path/to/opsview_restapi_token --pretty --data-format=json GET /rest/config/host?include_encrypted=1&s.name=<hostname1>&s.name=<hostname2>
```

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](#alternative-filters) section.

2. Generate encrypted values by running the following command:

```
sudo -iu opsview /opt/opsview/coreutils/bin/opsview_crypt
```

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.

```
"encrypted_snmpv3_authpassword" : "<enter encrypted value>",
"encrypted_snmpv3_privpassword" : "<enter encrypted value>",

"snmpv3_authprotocol" : "sha",
"snmpv3_privprotocol" : "aes128",
"snmpv3_username" : "<username>",
```

4. Update the configuration using the following command:

```
opsview_rest --token-file /path/to/opsview_restapi_token --pretty --data-format=json --content-file=/tmp/snmp_network_hosts.json PUT /rest/config/host
```

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

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

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

### Alternative filters

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

```
opsview_rest --token-file /path/to/opsview_restapi_token --pretty --data-format=json GET /rest/config/host"?include_encrypted=1&s.hostgroup.name=<hostgroup-name>" > /tmp/snmp_network_hosts.json
```

#### Host templates

```
opsview_rest --token-file /path/to/opsview_restapi_token --pretty --data-format=json GET /rest/config/host"?include_encrypted=1&s.hosttemplates.name=<template-name>" > /tmp/snmp_network_hosts.json
```


**Note**


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



For more information on how to generate and use the token file, see [opsview_rest](https://docs.itrsgroup.com/docs/opsview/6.11.7/rest-api/rest-api-background/api-common-examples/index.html#opsview_rest) documentation.


