Run Discovery via the API - Statseeker Documentation

Index

Overview
Example Discovery Requests
Discovery Related API Endpoints

Overview

Statseeker’s RESTful API v2.1 r16 (Statseeker v5.6.2) changes the way the API deals with the Discovery process. Anyone initiating Discovery via the API will need to update their scripts to address these changes.

The table below presents the new and updated API endpoints related to the Discovery process and links through to the API descriptions for each.

API Endpoint	Description
discover	Used to initiate a discovery process with: /api/v2.1/discover/execute Requires mode set to one of Discover, Hosts, Manual, or Rewalk Note: these values are case-sensitive and differ from those used in earlier API revisions Offers a range of Options which can be passed in as parameters to customize the Discovery, this customization only applies to that Discovery run
discover_config	Statseeker stores a single discover_config which provides the default configuration used for all Discovery processes. This default config: Targets all enabled ip_range_config entities References all snmp_credential entities The default values for iftype, ping_count, ping_rate, ping_skip, and sysdescr are found in Admin Tool > Network Discovery – Advanced Options > Advanced Options, and can be updated in the Admin Tool or via the API This default discover_config is automatically applied to every Discovery that does not feature an alternate discover_config as a parameter. Including an updated discover_config as a parameter will override the default for that Discovery.
discover_history	Contains details of completed Discoveries, including the discover_config used in that Discovery. Note: when retrieving discover_history records, start and finish are time fields and requirea timefilter (global or field-specific)
discover_hosts	Each discover_hosts entity is an entry in the server’s Hosts file, these entities are referenced when discover.mode=Hosts. The Hosts file support both IPv4 and IPv6 addresses.
ip_range_config	IPv4 Range configurations used to target the Discovery process, each consists of: At least one include range Optionally, one or more exclude ranges A list of snmp_credentials IDs Only the listed snmp_credentials will be sent to the IPs in the specified range An empty list will result in all saved snmp_credentials being referenced when attempting to communicate with devices in the specified range
snmp_credential	SNMPv1\v2\v3 credential configurations. A default Discovery references all known SNMP credentials when attempting to discover a device.
irc_to_sc_map	An entity automatically created when associating snmp_credentials entities with specific ip_range_config entities. There is no need to interact with this endpoint.

[top]

Example Discovery Requests

Default Network Discovery

Network Discovery targeting all enabled IP Address Range configurations and referencing all SNMP Credentials.

/api/v2.1/discover/execute?mode=Discover
[top]

Customized Network Discovery

Customize a Network Discovery by specifying an alternate discover_config object. This alternate configuration can restrict the IP Address Ranges or SNMP Credentials used by the discovery, and override any other default Discovery settings.

In this example we:

Use ip_range_configurations to specify specific snmp_credentails (identified by their id) to use with each IP Range configuration
Override the default iftype and sysdescr rules to further limit the devices and interfaces returned by the Discovery

/api/v2.1/discover/execute?mode=Discover&discover_config={"iftype":["ethernetCsmacd","fastEther","gigabitEthernet"],"ping_count":2,"ping_skip":256,"ping_rate":512,"sysdescr":["include Cisco","include Dell","include HP","include Juniper","include Linux"],"ranges":{"exclude":["10.100.44.1","10.100.44.254","10.100.44.10","10.100.45.1"],"include":["10.100.44.0/24","10.100.45.0/24"]},"ip_range_configurations":[{"ip_range":{"exclude":[],"include":["10.100.46.0/24"]},"name":"myIpRange","snmp_credentials":[2]},{"ip_range":{"exclude":[],"include":["10.100.46.[250-255]"]},"name":"anotherIpRange","snmp_credentials":[1]}],"snmp_credentials":[{"id":1,"version":2,"community":"public"},{"id":2,"version":2,"community":"notpublic"}]}
[top]

Manual Discovery with SNMPv3 Credentials

Manual Discovery requires a manual_config parameter containing:

ipaddress
manual_name
Either an SNMP Credentials object, or the ping-only option ("ping_only":true)

/api/v2.1/discover/execute?mode=Manual&manual_config=[{"ipaddress":"10.116.3.4","manual_name":"anotherPingOnly","ping_only":false,"id":3,"name":"SNMPv3sha512","version":3,"type":"SNMPv3","community":null,"auth_method":"sha512","auth_user":"SHAUsername","auth_pass":"071086065075067089070083031","priv_method":"aes256","priv_pass":"071086065075067089070083031","context":"context1"}]

[top]

Ping-Only Discovery using the Hosts File

A Ping-Only Discovery via IP Address Ranges is specified by setting mode="Ping Only Discover"
A ping-only Discovery via Hosts is specified by setting mode="Hosts" and snmp_versions=[] (an empty array)

/api/v2.1/discover/execute?mode=Hosts&snmp_versions=[]
[top]

Ping-Only Discovery, overriding the default IP Range Configurations with a custom range

/api/v2.1/discover/execute/?mode=Ping Only Discover&discover_config={"ping_count":2,"ping_rate":512,"ping_skip":256,"ranges":{"include":["10.100.59.[252-254]"],"exclude":[]}}
[top]

Rewalk Select Groups of Devices

The Rewalk can target all known devices, select devices, or select groups of devices. The groups option requires an array of group names.

/api/v2.1/discover/execute?mode=Rewalk&groups=["Baltimore","FortWorth"]
[top]

Retrieving Historical Discovery Records

Returning details on completed Discoveries that were initiated since the start of the day.

/api/v2.1/discover_history/?fields=mode,status,start,details,logfile&timefilter=range=start-of-today to now&timefmt=%A %H:%M:%S (%y-%m-%d)

Note:

The start and finish fields are time fields, so when requested they must be accompanied by a timefilter (global or field-specific)
By default, time fields are returned in epoch time, the timefmt parameter can be applied to turn this value into a more readable format. See Resource Endpoint for details on timefmt and other generic GET request parameters

[top]

Adding an IP Range Configuration

Adding a new IP Address Range Configuration requires a POST request to the ip_range_config including the configuration as a JSON object in the body of the request.

In this example we specify:

A single include range: 10.100.58.0/24
Multiple exclude ranges: 10.100.58.[15-240] & 10.100.58.[5-10]
A name for the IP Address Range Configuration: MyNewRangeConfig

cURLPythonRubyResponse


curl \
	-H "Accept: application/json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
	-X POST \
	"https://your.statseeker.server/api/v2.1/ip_range_config/?indent=3" \
	-d '{"data":[{"ip_range":{"include":["10.100.58.0/24"],"exclude":["10.100.58.[15-240]","10.100.58.[5-10]"]},"enabled":0,"name":"MyNewRangeConfig"}]}'


# import requests for handling connection and encoding
import requests
import json
def do_request(server, query, user, pword, reqData):
    # Run auth request
    headers = { 'Accept': 'application/json', 'Content-Type': 'application/x-www-form-urlencoded' }
    url = f'https://{server}/ss-auth'
    authData = {'user': user, 'password': pword}
    resp = requests.post(url, headers=headers, data=authData, verify=False)
    headers['Content-Type'] = 'application/json'
    url = f'https://{server}/{query}'
    print(f'Get Auth Token: {resp.status_code}')
    if resp.status_code == 200:    
        # Authentication successful
        myToken = resp.json()
        headers['Authorization'] = f'Bearer {myToken["access_token"]}'
        resp = requests.post(url, headers=headers, data=reqData, verify=False)
    if resp.status_code == 401:
        print(f'Token auth failed: {resp.status_code}, trying basic auth')
        # Either Authentication was unsuccessful, or API set to use basic auth
        # Try basic auth
        resp = requests.post(url, headers=headers, auth=(user, pword), data=reqData, verify=False)
    return resp

# Statseeker Server IP
server = 'your.statseeker.server'
# credentials
user = 'api_user'
pword = 'user_password'
# API root endpoint
query = 'api/v2.1'
# specify target endpoint
query += '/ip_range_config'
# optional response formatting
query += '/?indent=3&links=none'
# data
reqData = json.dumps({"data":[{"ip_range":{"include":["10.100.58.0/24"],"exclude":["10.100.58.[15-240]","10.100.58.[5-10]"]},"enabled":0,"name":"MyNewRangeConfig"}]})
# Run the request
resp = do_request(server, query, user, pword, reqData)
if resp.status_code == 200:
    print(resp.status_code)
    print(resp.json())
else:
    print(f'Error: {resp.status_code} {resp.reason}')


# install with: $ gem install rest-client
require "rest_client"
require "json"
require "base64"

def try_basic(server, query, user, pword, reqData)
	headers = {
		:content_type => "application/json"
	}
	url = "https://" + server + "/" + query
	headers["Authorization"] = "Basic " + Base64.encode64("#{user}:#{pword}")
	return RestClient::Request.execute(
		:method => :post,
		:url => url,
		:headers => headers,
		:verify_ssl => false,
		:payload => reqData
	)
end

def do_request(server, query, user, pword, reqData)
    # Run auth request
    headers = {
        :content_type => "application/x-www-form-urlencoded"
    }
    url = "https://" + server + "/ss-auth"
    authData = {
       :user => user,
       :password => pword
    }
    begin
        resp = RestClient::Request.execute(
            :method => :post,
            :url => url,
            :headers => headers,
            :verify_ssl => false,
            :payload => authData
        )
    rescue RestClient::Unauthorized
		# bad credentials
        try_basic(server, query, user, pword, reqData)
    else		
        # Authentication successful
		headers = {
		:content_type => "application/json"
		}	
        url = "https://" + server + "/" + query
        rdata = JSON.parse(resp)
        headers["Authorization"] = "Bearer " + rdata.fetch("access_token")
        return RestClient::Request.execute(
			:method => :post,
			:url => url,
			:headers => headers,
			:verify_ssl => false,
			:payload => reqData
        )
    end
	rescue RestClient::Unauthorized
		# Statseeker may be configured for basic auth
        try_basic(server, query, user, pword, reqData)
end
# Statseeker Server IP
$server = 'your.statseeker.server'
# api user credentials
$user = 'api_user'
$pword = 'user_password'
# api root endpoint
$query = 'api/v2.1'
# specify target endpoint
$query += '/ip_range_config'
# optional response formatting
$query += '/?indent=3&links=none'
# configure payload
$reqData = '{"data":[{"ip_range":{"include":["10.100.58.0/24"],"exclude":["10.100.58.[15-240]","10.100.58.[5-10]"]},"enabled":0,"name":"MyNewRangeConfig"}]}'
# Run the request
resp = do_request($server, $query, $user, $pword, $reqData)
puts "#{resp.to_str}"


{
    "version": "2.1",
    "revision": "16",
    "info": "The Statseeker RESTful API",
    "data": {
        "success": true,
        "errmsg": "ok",
        "time": 1726455388,
        "objects": [
            {
                "type": "ip_range_config",
                "sequence": 3,
                "status": {
                    "success": true,
                    "errcode": 0
                },
                "data_total": 1,
                "data": [
                    {
                        "enabled": 0,
                        "ip_range": {
                            "include": [
                                "10.100.58.0/24"
                            ],
                            "exclude": [
                                "10.100.58.[15-240]",
                                "10.100.58.[5-10]"
                            ]
                        },
                        "name": "MyNewRangeConfig",
                        "id": 2
                    }
                ]
            }
        ]
    }
}

Note: the above example doesn’t specify which SNMNP Credentials to associate with the IP Range. If a Discovery was run against this IP range configuration, all SNMP Credentials would be referenced and an irc_to_sc_map entity would be created for each snmp_credential that at least one IP responded to.

If you would like to restrict which SNMP Credentials are referenced when running Discovery against the IP range, then it can be specified in the ip_range_config by setting snmp_credentials – this field takes a list of snmp_credential IDs.

Example:

{"data":[{"ip_range":{"include":["10.100.58.0/24"],"exclude":["10.100.58.[15-240]","10.100.58.[5-10]"]},"enabled":1,"name":"MyNewRangeConfig2","snmp_credentials":[1,2,5]}]}

[top]

Updating an IP Range Configuration

Updating an IP Address Range Configuration requires a PUT request to the ip_range_config including the configuration changes as a JSON object in the body of the request.

In this example we:

Apply a filter to the name filter to identify the ip_range_config to be updated
Specify an alternate set of exclude ranges by updating the ip_range field
Note: the update is performed by replacing the existing ip_range value with a new value. A valid ip_range value requires at least one include range statement, so even though we are only updating the exclude statement, we are required to also specify an include statement.

cURLPythonRubyResponse


curl \
	-H "Accept: application/json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
	-X PUT \
	"https://your.statseeker.server/api/v2.1/ip_range_config/?links=none&indent=3" \
	-d '{"fields":{"name":{"field":"name","filter":{"query":"='MyNewRangeConfig'"}}},"data":[{"ip_range":{"include":["10.100.58.0/24"],"exclude":["10.100.58.[15-240]"]}}]}'


# import requests for handling connection and encoding
import requests
import json
def do_request(server, query, user, pword, reqData):
    # Run auth request
    headers = { 'Accept': 'application/json', 'Content-Type': 'application/x-www-form-urlencoded' }
    url = f'https://{server}/ss-auth'
    authData = {'user': user, 'password': pword}
    resp = requests.post(url, headers=headers, data=authData, verify=False)
    headers['Content-Type'] = 'application/json'
    url = f'https://{server}/{query}'
    print(f'Get Auth Token: {resp.status_code}')
    if resp.status_code == 200:    
        # Authentication successful
        myToken = resp.json()
        headers['Authorization'] = f'Bearer {myToken["access_token"]}'
        resp = requests.put(url, headers=headers, data=reqData, verify=False)
    if resp.status_code == 401:
        print(f'Token auth failed: {resp.status_code}, trying basic auth')
        # Either Authentication was unsuccessful, or API set to use basic auth
        # Try basic auth
        resp = requests.put(url, headers=headers, auth=(user, pword), data=reqData, verify=False)
    return resp

# Statseeker Server IP
server = 'your.statseeker.server'
# credentials
user = 'api_user'
pword = 'user_password'
# API root endpoint
query = 'api/v2.1'
# specify target endpoint
query += '/ip_range_config'
# optional response formatting
query += '/?indent=3&links=none'
# data
reqData = json.dumps({"fields":{"name":{"field":"name","filter":{"query":"='MyNewRangeConfig'"}}},"data":[{"ip_range":{"include":["10.100.58.0/24"],"exclude":["10.100.58.[15-240]"]}}]})
# Run the request
resp = do_request(server, query, user, pword, reqData)
if resp.status_code == 200:
    print(resp.status_code)
    print(resp.json())
else:
    print(f'Error: {resp.status_code} {resp.reason}')


# install with: $ gem install rest-client
require "rest_client"
require "json"
require "base64"

def try_basic(server, query, user, pword, reqData)
	headers = {
		:content_type => "application/json"
	}
	url = "https://" + server + "/" + query
	headers["Authorization"] = "Basic " + Base64.encode64("#{user}:#{pword}")
	return RestClient::Request.execute(
		:method => :post,
		:url => url,
		:headers => headers,
		:verify_ssl => false,
		:payload => reqData
	)
end

def do_request(server, query, user, pword, reqData)
    # Run auth request
    headers = {
        :content_type => "application/x-www-form-urlencoded"
    }
    url = "https://" + server + "/ss-auth"
    authData = {
       :user => user,
       :password => pword
    }
    begin
        resp = RestClient::Request.execute(
            :method => :post,
            :url => url,
            :headers => headers,
            :verify_ssl => false,
            :payload => authData
        )
    rescue RestClient::Unauthorized
		# bad credentials
        try_basic(server, query, user, pword, reqData)
    else		
        # Authentication successful
		headers = {
		:content_type => "application/json"
		}	
        url = "https://" + server + "/" + query
        rdata = JSON.parse(resp)
        headers["Authorization"] = "Bearer " + rdata.fetch("access_token")
        return RestClient::Request.execute(
			:method => :put,
			:url => url,
			:headers => headers,
			:verify_ssl => false,
			:payload => reqData
        )
    end
	rescue RestClient::Unauthorized
		# Statseeker may be configured for basic auth
        try_basic(server, query, user, pword, reqData)
end
# Statseeker Server IP
$server = 'your.statseeker.server'
# api user credentials
$user = 'api_user'
$pword = 'user_password'
# api root endpoint
$query = 'api/v2.1'
# specify target endpoint
$query += '/ip_range_config'
# optional response formatting
$query += '/?indent=3&links=none'
# configure payload
$reqData = '{"fields":{"name":{"field":"name","filter":{"query":"='MyNewRangeConfig'"}}},"data":[{"ip_range":{"include":["10.100.58.0/24"],"exclude":["10.100.58.[15-240]"]}}]}'
# Run the request
resp = do_request($server, $query, $user, $pword, $reqData)
puts "#{resp.to_str}"


{

   "version":"2.1",

   "revision":"16",

   "info":"The Statseeker RESTful API",

   "data":{

      "success":true,

      "errmsg":"ok",

      "time":1726459825

   }

}

[top]

Deleting an IP Range Configuration

Deleting an IP Address Range Configuration requires a DELETE request to the ip_range_config

In this example we apply a filter to the name filter to identify the ip_range_config to be deleted.

cURLPythonRubyResponse


curl \
	-H "Accept: application/json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
	-X DELETE \
	"https://your.statseeker.server/api/v2.1/ip_range_config/?links=none&indent=3" \
	-d '{"fields":{"name":{"field":"name","filter":{"query":"='MyNewRangeConfig'"}}}}'


# import requests for handling connection and encoding
import requests
import json
def do_request(server, query, user, pword, reqData):
    # Run auth request
    headers = { 'Accept': 'application/json', 'Content-Type': 'application/x-www-form-urlencoded' }
    url = f'https://{server}/ss-auth'
    authData = {'user': user, 'password': pword}
    resp = requests.post(url, headers=headers, data=authData, verify=False)
    headers['Content-Type'] = 'application/json'
    url = f'https://{server}/{query}'
    print(f'Get Auth Token: {resp.status_code}')
    if resp.status_code == 200:    
        # Authentication successful
        myToken = resp.json()
        headers['Authorization'] = f'Bearer {myToken["access_token"]}'
        resp = requests.delete(url, headers=headers, data=reqData, verify=False)
    if resp.status_code == 401:
        print(f'Token auth failed: {resp.status_code}, trying basic auth')
        # Either Authentication was unsuccessful, or API set to use basic auth
        # Try basic auth
        resp = requests.delete(url, headers=headers, auth=(user, pword), data=reqData, verify=False)
    return resp

# Statseeker Server IP
server = 'your.statseeker.server'
# credentials
user = 'api_user'
pword = 'user_password'
# API root endpoint
query = 'api/v2.1'
# specify target endpoint
query += '/ip_range_config'
# optional response formatting
query += '/?indent=3&links=none'
# data
reqData = json.dumps({"fields":{"name":{"field":"name","filter":{"query":"='MyNewRangeConfig'"}}}})
# Run the request
resp = do_request(server, query, user, pword, reqData)
if resp.status_code == 200:
    print(resp.status_code)
    print(resp.json())
else:
    print(f'Error: {resp.status_code} {resp.reason}')


# install with: $ gem install rest-client
require "rest_client"
require "json"
require "base64"

def try_basic(server, query, user, pword, reqData)
	headers = {
		:content_type => "application/json"
	}
	url = "https://" + server + "/" + query
	headers["Authorization"] = "Basic " + Base64.encode64("#{user}:#{pword}")
	return RestClient::Request.execute(
		:method => :post,
		:url => url,
		:headers => headers,
		:verify_ssl => false,
		:payload => reqData
	)
end

def do_request(server, query, user, pword, reqData)
    # Run auth request
    headers = {
        :content_type => "application/x-www-form-urlencoded"
    }
    url = "https://" + server + "/ss-auth"
    authData = {
       :user => user,
       :password => pword
    }
    begin
        resp = RestClient::Request.execute(
            :method => :post,
            :url => url,
            :headers => headers,
            :verify_ssl => false,
            :payload => authData
        )
    rescue RestClient::Unauthorized
		# bad credentials
        try_basic(server, query, user, pword, reqData)
    else		
        # Authentication successful
		headers = {
		:content_type => "application/json"
		}	
        url = "https://" + server + "/" + query
        rdata = JSON.parse(resp)
        headers["Authorization"] = "Bearer " + rdata.fetch("access_token")
        return RestClient::Request.execute(
			:method => :delete,
			:url => url,
			:headers => headers,
			:verify_ssl => false,
			:payload => reqData
        )
    end
	rescue RestClient::Unauthorized
		# Statseeker may be configured for basic auth
        try_basic(server, query, user, pword, reqData)
end
# Statseeker Server IP
$server = 'your.statseeker.server'
# api user credentials
$user = 'api_user'
$pword = 'user_password'
# api root endpoint
$query = 'api/v2.1'
# specify target endpoint
$query += '/ip_range_config'
# optional response formatting
$query += '/?indent=3&links=none'
# configure payload
$reqData = '{"fields":{"name":{"field":"name","filter":{"query":"='MyNewRangeConfig'"}}}}'
# Run the request
resp = do_request($server, $query, $user, $pword, $reqData)
puts "#{resp.to_str}"


{

   "version":"2.1",

   "revision":"16",

   "info":"The Statseeker RESTful API",

   "data":{

      "success":true,

      "errmsg":"ok",

      "time":1726460004

   }

}

[top]

Discovery Related API Endpoints

Discover

Endpoint

discover

Description

Discovery Process

Fields

Field ID	Field Title	Type	Get, Add, Update	Description
config	Config	json	G	A JSON object containing the configuration options used for the discovery process
details	Details	json	G	A JSON object containing details about what has occurred in the discovery process
duration	Duration	integer	G	The length of time the discovery process has taken
finish	Finish Time	time	G	The timestamp that the discovery process finished
id	ID	integer	G	Unique Identifier for the discovery process
logfile	Log File	string	G	The filesystem location of the log file for the discovery process
mode	Mode	string	G	The mode the discovery process was run in One of: Hosts – Host Discovery Rewalk – Rewalk Manual – Manual Device Addition Discover – Network Discovery
start	Start Time	time	G	The timestamp that the discovery process started
status	Status	string	G	The current status of the discovery process
user	User	string	G	The user that triggered the discover process (‘auto’ if triggered automatically)

Options

Option	Description
block	Block if another discover is running (default to false) false: Return an error if another discover is running true: Block if another discover is running
data	A configuration used for specifying IP Ranges
datafile	Path to config file containing IP Range Configuration (uploaded)
devices	Optional array of devices to rewalk (for ‘Rewalk’ mode only)
discover_add_ping_only	When running an snmp discovery, if a device is pingable, but doesn’t respond to snmp, still add device as ping only(Defaults to false) false: Don’t add devices as ping only devices when devices do not respond to snmp true: Add devices which don’t respond to snmp as ping only devices (Default only when snmp_versions is an empty list)
discover_adminstatus	Override Advanced options for interface admin status polling false: Disable interface admin status polling for newly discovered devices. true: Enable interface admin status polling for newly discovered devices.
discover_config	Override discover configuration.
discover_getNext	Discover using SNMP getNext (Not valid for ‘Rewalk’, defaults to false) false: Use bulk requests for discovery true: Use getNext requests for discovery
discover_grouping	If runPostProcessing is enabled, create groups based on configured autogroup rules (Defaults to discover_grouping in Advanced Options) false: Even if runPostProcessing is enabled, don’t run the configured autogrouping rules true: If runPostProcessing is enabled, run the configured autogrouping rules
discover_minimal	Perform minimal discover (Not valid for ‘Rewalk’, defaults to false) false: Perform full discover true: Perform minimal discover (only walk a few core tables)
discover_nucast	Override Advanced options for Non Unicast monitoring global: Set non unicast polling based on Advanced options value off: Override Advanced options and disable non unicast polling for newly discovered interfaces on: Override Advanced options and enable non unicast polling for newly discovered interface
discover_operstatus	Override Advanced options for interface operstatus polling false: Disable interface operstatus polling for newly discovered devices. true: Enable interface operstatus polling for newly discovered devices.
discover_prune_existing_devices	When running a discover, Don’t include IP addresses already in Product (Defaults to false) false: Include IP Addresses already in Product when performing a discovery true: Don’t include IP Addresses already in Product when performing a discovery
discover_rules	Override Custom Data Type discover rules.
email	A array of email addresses. When select the output log will be emailed to these addresses on completion of the task. If a ‘logfile’ is specified, the logfile will be kept, otherwise a temporary logfile is used which is later removed. If a ‘subject’ is given, this will be used for the email subject, otherwise a default subject line is used
groups	Optional array of groups to rewalk (for ‘Rewalk’ mode only)
interface_speed_autogrouping	If runPostProcessing is enabled, create groups based on interface speeds (Defaults to discover_grouping in Advanced Options) false: Even if runPostProcessing is enabled, don’t run the interface autogrouping true: If runPostProcessing is enabled, run the interface autogrouping
interface_type_autogrouping	If runPostProcessing is enabled, create groups based on interface types (Defaults to discover_grouping in Advanced Options) false: Even if runPostProcessing is enabled, don’t run the interface autogrouping true: If runPostProcessing is enabled, run the interface autogrouping
logfile	Path to store the discover log (defaults to ~/nim/etc/discover.log)
manual_config	Manual Configuration which has been generated from a previous discover (after processing data or datafile)
manual_force_add	When running a manual discover, Force add devices from configuration into Product (Defaults to false) false: Only add devices into product if device is both ping and snmp discoverable true: Even if IP address is not pingable, and snmp fails, still add device to Product based on configuration
mode	The type of discovery to run Discover: Discover all devices in the ip ranges file Hosts: Discover devices from the host file Manual: Discover using provided configuration Ping Only Discover: Discover all devices in the ip ranges via icmp only Rewalk: Rewalk devices that have already been discovered
ping_only_force_add	When running a Ping Only Discover, Force add ping only devices for secondary IP addresses of monitored devices (Defaults to false) false: Only add devices into product if device is ping discoverable and doesn’t already exist true: Even if IP address is associated to monitored device, add device as a ping only device
rediscover_custom_data_types	When walking custom data type tables, try to rediscover Custom Data types if already discovered (Defaults to false) false: Only walk tables of entity types already discovered for device true: Walk all snmp tables associated to defined entity types.
retest_snmp_credentials	re-test snmp credentials for know devices all: Re-test snmp credentials for all existing devices down: Re-test snmp credentials for existing devices which a ping up, but snmp down none: Don’t re-test snmp credentials for existing devices
runPostProcessing	Whether to run discover post-processing steps. Currently this includes Autogrouping and the Hardware Inventory report generation. This will result in a quicker discover but means that the added devices won’t be added to any Autogroups or the Hardware Inventory report until the next full discover. (defaults to true) false: Don’t perform post processing steps true: Perform post processing steps
snmp_max_files	Maximum number of walk files opened by an Snmpwalk(Defaults to value in snmp.cfg)
snmp_max_repetitions	SNMP Max Repetition to use for each walk (Defaults to value in snmp.cfg)
snmp_retry_count	SNMP Retry Count to use for each walk command (Defaults to 2)
snmp_timeout	SNMP Timeout in seconds to use for each get command (Defaults to 5)
snmp_versions	Array of SNMP versions to check during a discovery (defaults to [ 2, 3 ]
snmp_walk_timeout	SNMP Timeout in seconds to use for each walk command (Defaults value defined in Advanced options or 10)
snmp_window_size	SNMP Window Size to use for each walk command (Defaults to 10)
snmperrlog	Enable SNMP error logging (default to false) false: Disable SNMP error logging true: Enable SNMP error logging
subject	The subject line to use if the ’email’ option is specified
verbose	Verbose level for the output (defaults to 0) 0: Disable verbose output 1: Enable verbose output (low) 2: Enable verbose output (medium) 3: Enable verbose output (high)

[top]

Discover Configuration

Endpoint

discover_config

Description

The configuration options for Statseeker’s discovery mechanism

Fields

Field ID	Field Title	Type	Get, Add, Update	Description
id	ID	integer	G	Discover config identifier/key
iftype	Interface Types	object	G, U	Comma separated list of interface types to include
ip_range_configurations	Per IP Address Range Configuration	object	G	A list of Discover Configuration objects associated to IP Address Ranges
ping_count	Ping Run Count	integer	G, U	Number of passes for the ping discover
ping_rate	Ping Rate	integer	G, U	Number of pings to send per second
ping_skip	Ping Skip	integer	G, U	Number of ipaddress to skip between each ping
ranges	Ranges	object	G	Comma separated discover ranges (using include/exclude syntax)
snmp_credentials	SNMP Credentials	object	G	A list of SNMP Credentials to use for discovery
sysdescr	SysDescr	object	G, U	Comma separated SysDescr values to decide which devices to discover

[top]

Discover History

Endpoint

discover_history

Description

This object contains details about current and past discovery and rewalk processes.

Fields

Field ID	Field Title	Type	Get, Add, Update	Description
config	Config	json	G, A (required)	A JSON object containing the configuration options used for the discovery process
datafile	Data File	string	G, A, U	The filesystem location of the compress data file for the discovery process(This may be removed based on data autorotation)
details	Details	json	G, A, U	A JSON object containing details about what has occurred in the discovery process
duration	Duration	integer	G, A, U	The length of time the discovery process has taken
finish	Finish Time	time	G, A, U	The timestamp that the discovery process finished
id	ID	integer	G	Unique Identifier for the discovery process
logfile	Log File	string	G, A, U	The filesystem location of the log file for the discovery process(This may be removed based on log autorotation
mode	Mode	string	G, A (required)	The mode the discovery process was run in One of: Manual – Manual Device Addition Ping Only Discover – Ping Only Discovery Hosts – Host Discovery Rewalk – Rewalk Discover – Network Discovery
start	Start Time	time	G, A (required)	The timestamp that the discovery process started
status	Status	string	G, A, U	The current status of the discovery process
user	User	string	G, A (required)	The user that triggered the discover process (‘auto’ if triggered automatically)

[top]

Discover Hosts

Endpoint

discover_hosts

Description

Hosts used for discovery

Fields

Field ID	Field Title	Type	Get, Add, Update	Description
enable	Enabled	integer	G, A, U	Whether this host is enabled for discovery (1 = enabled, 0 = disabled)
hostname	Hostname	string	G, A (required), U	Name of the host
id	ID	integer	G	Host identifier
ipaddress	IP Address	string	G, A (required), U	IP address of the host

[top]

IP Range Configuration

Endpoint

ip_range_config

Description

This defines the IP Ranges

Fields

Field ID

Field Title

Type

Get, Add, Update

Description

enabled

Enabled

integer

G, A, U

Indicates whether this IP Range Configuration has been enabled.

integer

G, A, U

IP Range Configuration ID

ip_range

IP Range

json

G, A (required), U

An object containing include and exclude arrays of IPv4 and IPv6 Ranges.

name

Name

string

G, A (required), U

Name of IP Range Configuration

snmp_credentials

SNMP Credential IDs

object

G, A, U

Array of SNMP Credential IDs (add and update only)

Format	Description
list	Array of snmp_credential ids to assign to this configuration

Links

Link	Description	Link Target
IRCtoSCMapLink	Link to IP Range Configuration to SNMP Credential Map	irc_to_sc_map

[top]

IP Range Configuration to SNMP Credential Map

Endpoint

irc_to_sc_map

Description

This is an intermediate table for linking IP Range Configurations to SNMP Credentials

Fields

Field ID	Field Title	Type	Get, Add, Update	Description
id	ID	integer	G, A, U	SNMP Credential identifier/key
ip_range_config	IP Range Configuration	integer	G, A (required), U	ID of the IP Range Configuration
snmp_credential	SNMP Credential ID	integer	G, A (required), U	ID of the SNMP Credential

Links

Link	Description	Link Target
ipRangeConfigLink	Link to IP Range Configuration	ip_range_config
snmpCredentialLink	Link to SNMP Credential	snmp_credential

[top]

SNMP Credential Details

Endpoint

snmp_credential

Description

The saved SNMP Credentials which are used for discovery and associating to SNMP monitored devices

Fields

Field ID

Field Title

Type

Get, Add, Update

Description

auth_method

Authentication

string

G, A, U

The SNMPv3 Authentication Method
One of:

None – None
SHA256 – SHA256
SHA1 – SHA1
MD5 – MD5
SHA224 – SHA224
SHA384 – SHA384
SHA512 – SHA512

auth_pass

Authentication Password

string

G, A, U

The Password to use when authenticating an SNMPv3 request

auth_user

Authentication User

string

G, A, U

The Username to use when authenticating an SNMPv3 request

community

Community

string

G, A, U

SNMPv1 or SNMPv2 community string

context

Context

string

G, A, U

The SNMPv3 Context

integer

SNMP Credential identifier/key

ip_range_configs

IP Range Config IDs

object

G, A, U

Array of IP Range Configs IDs (add and update only)

Format	Description
list	Array of ip_range_config ids to assign to this configuration

name

Name

string

G, A (required), U

Name identifer for SNMP Credentials

priv_method

Privacy

string

G, A, U

The Privacy Method used when encrypting/decrypting SNMPv3 requests and responses
One of:

DES – DES
DES3 – Triple DES
AES192 – AES 192
AES512 – AES 512
None – None
AES – AES
AES256 – AES 256

priv_pass

Privacy Password

string

G, A, U

The Password to use when encrypting/decrypting SNMPv3 requests and responses

version

SNMP Version

integer

G, A (required), U

The SNMP version

Options

Option	Description
auth_pass_encrypted	Indicates whether auth_pass has already been encrypted when calling add or update false: Indicates that auth_pass has not been encrypted (default if not provided) true: Indicates that auth_pass has already been encrypted
priv_pass_encrypted	Indicates whether priv_pass has already been encrypted when calling add or update false: Indicates that priv_pass has not been encrypted (default if not provided) true: Indicates that priv_pass has already been encrypted

Links

Link	Description	Link Target
IRCtoSCMapLink	Link to IP Range Configuration to SNMP Credential Map	irc_to_sc_map

[top]