JSON-RPC¶

This documentation provides technical details of the NetLD/ThirdEye integration API. The NetLD/ThirdEye server exposes a JSON-RPC¹ 2.0 API over HTTPS for language neutral integration from external systems. There are many JSON-RPC 2.0 client libraries available for all major languages². See the Examples directory for sample scripts in various languages.

The use of JSON-RPC means that the underlying data sent to or received from the server is in JSON (JavaScript Object Notation) format. All strings are encoded using UTF-8 encoding, no other encodings are supported.

The access URL for Net LineDancer is:

https://server/rest?j_username=username&j_password=password

Where server, username, and password are values correct for your installation.

All JSON-RPC requests are performed using the POST method. If you hit the URL using the GET method, no operation will be performed, but you will get an “OK” message if the credentials are valid.

The API documentation shows examples of “raw” JSON requests, but it is recommended that you use JSON-RPC libraries appropriate for your language of choice, which will handle the JSON generation for you.

¹ http://www.jsonrpc.org/specification ² http://en.wikipedia.org/wiki/JSON-RPC

Inventory¶

The inventory API provides the core functionality of manipulating devices in the Net LineDancer inventory, including: adding devices, deleting devices, modifying devices, searching devices, etc.

See the Inventory Objects section for a description of the various objects consumed and returned by these APIs.

Inventory.createDevice¶

Add a device to the inventory, in the specified network. If the device was created successfully, the return value is null, otherwise an error message is returned.

Parameters¶

Parameter	Type	Description
network	String	Name of an existing network, e.g. “Default”
ipAddress	String	IPv4 or IPv6 address
adapterId	String	The ID of the adapter to use for backup, see Appendix A

Return: an error message or `null`¶

Inventory.deleteDevice¶

Delete a device from the inventory.

Parameters¶

Parameter	Type	Description
network	String	Name of an existing network, e.g. “Default”
ipAddress	String	IPv4 or IPv6 address

Return: `null`¶

Inventory.getDevice¶

The Inventory.getDevice method returns a Device object as described above, or null if the requested device does not exist.

Parameters¶

Parameter	Type	Description
network	String	Name of an existing network, e.g. “Default”
ipAddress	String	IPv4 or IPv6 address

Return: `Device` object or `null`¶

Inventory.updateDevice¶

The Inventory.updateDevice method is used to update an existing device in the inventory. It requires only network and ipAddress as parameters, all other parameters are optional.

Parameter	Type	Description
network	String	Name of the device’s network
ipAddress	String	IPv4 or IPv6 address
newNetwork	String	A new Network name for the device, or null
newIpAddress	String	A new IP address for the device, or null
newAdapterId	String	A new AdapterId for the device, or null
newHostname	String	A new Hostname for the device, or null

Return: `null`¶

Python Example:¶

error = netld.call('Inventory.updateDevice', 'Default', '10.0.0.1', null, null, null, 'newhostname')

Inventory.updateDevices¶

The Inventory.updateDevices method updates Adapter IDs and/or custom field values for multiple devices in a single operation.

Parameter	Type	Description
ipCsv	String	A comma separated list of devices of the form IPAddress@network
adapterId	String	The new adapter ID or `null` if it should remain unmodified.
customFields	String Array	An indexed array of custom fields

The ipCsv parameter is a comma separated list of devices of the form IPAddress@network (e.g. 192.168.0.254@NetworkA *,*10.0.0.1@NetworkB).

The adapterId parameter is either a new Adapter ID to assign to the specified devices, or null to leave the device’s Adapter ID at their current values. See Appendix A for a list of valid Adapter IDs.

The customFields parameter is an array of UTF-8 string values. The first element of the array corresponds to the Custom 1 custom field, and the fifth element corresponds to the Custom 5 custom field. Elements of the customFields array that are null will leave the corresponding custom fields at their current values.

Return: `null`¶

Python example:

netld.call('Inventory.updateDevices',
           '192.168.0.254@NetworkA,192.168.0.252@NetworkA',
           null,
           ['Tokyo HQ', 'Rack 1F-8'])

Inventory.search¶

The Inventory.search method is the fundemental way of retrieving devices from the inventory. Search supports many criteria, and the criteria can be combined to perform powerful searches.

Parameter	Type	Description
network	String Array	An array of networks to search. It is now possible to search across multiple networks in the same operation.
scheme	String	A single scheme name, or comma-separated list of scheme names (see table below)
query	String	The query associated with the scheme(s) specified. If there are multiple schemes specified, the query parameter should contain new-line (n) characters between each query string
pageData	Object	A `PageData` object defining the offset where retrieval should begin and page size
sortColumn	String	A string indicating the `Device` object attribute the results should be sorted by
descending	Boolean	A boolean flag indicating whether results should be sorted in descending or ascending order

The scheme parameter is a single value or a comma separated list of search schemes from the following table:

Scheme	Description
ipAddress	Searches the inventory based on a specific IP address (e.g. 192.168.0.254) or a CIDR (10.0.0.0/24)
interfaceIpAddress	Searches the inventory based on a specific IP address (e.g. 192.168.0.254) or a CIDR (10.0.0.0/24) where the search includes not only the management IP address but also all of the device interface IP addresses
hostname	Searches the inventory based on a specified hostname. The specified hostname may be an exact hostname or a name with leading and/or trailing wildcard character (asterisk)
vendor	Searches the inventory based on the specified Adapter ID. See Appendix A for a list of Adapter IDs
serial	Searches the inventory based on a specified serial number. The specified serial number may be an exact serial number or a string with leading and/or trailing wildcard character (asterisk)
status	Searches the inventory based on the specified inventory status. The status string (specified in the query parameter) must be one of these values: “N” (NONE), “S” (SUCCESS), “C” (COMPLIANCE VIOLATION), “I” (INVALID CREDENTIALS), “F” (OTHER FAILURE)
lastChange	Searches the inventory for devices whose configuration has changed during the specified time period. Valid values are: “24h”, “7d”, “30d”, or a range in this format: YYYY-MM-DD/YYYY-MM-DD (eg. 2012-01-01/2012-06-01)
custom	Searches the inventory for devices whose custom field values match the specified values. The `query` parameter specifies a string that contains a comma-separated list of key/value pairs, i.e “custom2=tokyo*,custom4=12345”. The value portion may contain leading and/or trailing wildcard characters.
tag	Searches the inventory for devices which are tagged with the tags specified in the `query` parameter. The `query` parameter specifies a string that can contain tag names separated by “AND” or “OR”, i.e. “tokyo AND firewall”.

The query parameter defines the query criteria to be used and is in association with the schemes defined by the scheme parameter. For example, if you wish to search based on scheme ipAddress and hostname you would specify a scheme parameter of “ipaddress,hostname”, and a query parameter of “192.168.0.0/24ntokyo*”. Note the newline character between the ipAddress query value and the hostname query value.

Return: A `PageData` object¶

The PageData object that is returned will contain an attribute called devices, which is an array of Device objects. If the initial offset that is passed is zero (0), the returned PageData object will also contain a populated total attribute, telling you how many total results are available. By incrementing the offset by pageSize you can retrieve subsequent pages of results. When offset + pageSize is greater than or equal to total there are no more results available.

Sample Request JSON:¶

{
   "jsonrpc": "2.0",
   "method": "Inventory.search",
   "params": {
              "network": ["Default"],
              "scheme": "ipAddress",
              "query": "10.0.3.0/24",
              "pageData": {
                           "offset": 0,
                           "pageSize": 100
                          },
              "sortColumn": "ipAddress",
              "descending": false
             },
   "id": 1
}

Sample Response JSON:¶

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": {
      "offset": 0,
      "pageSize": 100,
      "total": 2,
      "devices": [
         {
            "ipAddress": "10.0.3.1",
            "hostname": "C2611",
            "adapterId": "Cisco::IOS",
            "deviceType": "Router",
            "hardwareVendor": "Cisco",
            "model": "CISCO2611",
            "softwareVendor": "Cisco",
            "osVersion": "12.1(19)",
            "backupStatus": "SUCCESS",
            "complianceState": 0,
            "lastBackup": 1410324616600,
            "lastTelemetry": null,
            "memoSummary": null,
            "custom1": "",
            "custom2": "",
            "custom3": "",
            "custom4": "",
            "custom5": "",
            "network": "Default",
            "serialNumber": "JAB03060AX0"
         },
         {
            "ipAddress": "10.0.3.6",
            "hostname": "C2611-2",
            "adapterId": "Cisco::IOS",
            "deviceType": "Router",
            "hardwareVendor": "Cisco",
            "model": "CISCO2611XM-2FE",
            "softwareVendor": "Cisco",
            "osVersion": "12.4(12)",
            "backupStatus": "SUCCESS",
            "complianceState": 0,
            "lastBackup": 1410324618367,
            "lastTelemetry": null,
            "memoSummary": null,
            "custom1": "",
            "custom2": "",
            "custom3": "",
            "custom4": "",
            "custom5": "",
            "network": "Default",
            "serialNumber": "JAE07170Q8S"
         }
      ]
   }
}

Sample Request JSON combining two search schemes:¶

{
   "jsonrpc": "2.0",
   "method": "Inventory.search",
   "params": {
              "network": ["Default"],
              "scheme": "ipAddress,custom",
              "query": "10.0.3.0/24\ncustom2=New York*,custom4=core",
              "pageData": {
                           "offset": 0,
                           "pageSize": 100
                          }
             },
   "id": 1
}

Inventory Objects¶

Device¶

Field	Type	Description
ipAddress	String	The IPv4 or IPv6 address of the device
hostname	String	The hostname of the device
network	String	The name of the managed network that the device resides in
adapterId	String	The NetLD “Adapter ID” used to manage this device
deviceType	String	The type of the device, “router”, “switch”, “firewall”, etc.
hardwareVendor	String	The hardware vendor who manufactured the device
model	String	The model number of the device
softwareVendor	String	The operating system vendor of the device
osVersion	String	The vendor specific OS version number string
backupStatus	String	The backup status of the device (SUCCESS, FAILURE, INVALID_CREDENTIAL, etc.)
complianceState	Integer	The compliance status of the device (0=compliant, 1=unsaved changes, 2=policy violations)
lastBackup	Integer	The timestamp of the most recent backup (in Unix Epoch time milliseconds)
lastTelemetry	Integer	The timestamp of the most recent neighbor collection (in Unix Epoch time milliseconds)
memoSummary	String	The first 60 characters of the device memo, or null
custom1	String	The custom1 value, or null
custom2	String	The custom2 value, or null
custom3	String	The custom3 value, or null
custom4	String	The custom4 value, or null
custom5	String	The custom5 value, or null
serialNumber	String	The chassis serial number of the device, or null if not available

PageData¶

Attribute	Type	Description
offset	Integer	The starting `offset` in the results to begin retrieving `pageSize` number of `Device` objects. This value is required when `PageData` is used as a parameter.
pageSize	Integer	The maximum number of `Device` objects to retrieve in a single method call. This value is required when `PageData` is used as a parameter.
total	Integer	This value is set and retrieved from the server when an `offset` of zero (0) is passed. This indicates the total number of `Device` objects available. This value is ignored when `PageData` is used as a parameter.
devices	Array	An array of `Device` objects. This value is ignored when `PageData` is used as a parameter.

Inventory.getDeviceHardware¶

The Inventory.getDeviceHardware returns a list of hardware of the requested device.

Parameters¶

Parameter	Type	Description
ipAddress	String	IPv4 or IPv6 address
network	String	Name of the device’s network

Return: list of `Hardware` Objects¶

Networks¶

The networks API provides the functionality for managing the managed network definitions.

See the Objects section for a description of the various objects consumed and returned by these APIs.

Methods¶

Networks.defineManagedNetwork¶

Create a new Managed Network within the system.

Parameters¶

Parameter	Type	Description
networkName	String	The network name
bridgeName	String	The name of the smart bridge

Return: void¶

Networks.getManagedNetwork¶

Get the Managed Network identified by name.

Parameters¶

Parameter	Type	Description
networkName	String	The network name

Return: A ManagedNetwork object¶

Networks.getManagedNetworkNames¶

Get the names of the Managed Networks that have been defined.

Parameters¶

None

Return: An array of Strings¶

Networks.getAllManagedNetworks¶

Get a list of all Managed Networks that have been defined.

Parameters¶

None

Return: An array of ManagedNetwork objects¶

Networks.deleteManagedNetwork¶

Delete a Managed Network identified by the name.

Parameters¶

Parameter	Type	Description
networkName	String	The network name

Return: void¶

Networks.updateManagedNetwork¶

Update a Managed Network’s information using the contents of the supplied ManagedNetwork instance. This instance must encapsulate information about a Managed Network that actually exists, otherwise an exception is thrown.

Parameters¶

Parameter	Type	Description
network	ManagedNetwork	The network to update

Return: void¶

Networks.getManagedNetworksByBridge¶

Get all managed networks by bridge.

Parameters¶

Parameter	Type	Description
bridgeName	String	The smart bridge name

Return: An array of ManagedNetwork objects¶

Objects¶

ManagedNetwork¶

Attribute	Type	Description
name	String	The managed network name
bridgeName	String	The name of the associated smart bridge
online	Boolean	The current online state of the bridge

Jumphosts¶

The Jumphost service allows configuration of jumphost parameters on specific networks.

Methods¶

Jumphost.getJumphostForNetwork¶

Get the jumphost configuration for a specified network, if it exists.

Parameters¶

Parameter	Type	Description
networkName	String	The network name

Return: a hashmap (key/value pairs) of jumphost settings, or null if none exist for the specified network¶

Python example:

from jsonrpc import JsonRpcProxy, JsonError

# netldHost should be defined as a variable containing the IP address/hostname of the NetLD server
netld_svc = JsonRpcProxy.fromHost(netldHost, "admin", "password")

network = "Default"

properties = netld_svc.call('Jumphost.getJumphostForNetwork', network)

for key in properties.keys():
   print key + ": " + properties[key]

netld_svc.call('Security.logoutCurrentUser')

Note: The jsonrpc functions are defined in jsonrpc.py in the SDK Examples/Python folder. Simply include that file in the same directory as your script.

Jumphost.saveJumphost¶

Create/update jumphost settings for a specified network. Ideally, when updating jumphost settings for a specific network it is recommended to first retrieve the properties via Jumphost.getJumphostForNetwork, modify them, and then use this method to save them. This ensures that any internal use properties that exists are not overwritten.

Parameters¶

Parameter	Type	Description
networkName	String	The network name
properties	Map	A JSON map of key/value pairs, as documented below

Return: void¶

The following are the required keys that must be present in the properties parameter:

Field	Value	Description
enabled	`"true"`/`"false"`	whether the jumphost is enabled or not
host	IP address/hostname	The IP address/hostname of the jumphost
username	String	the username required to login to the jumphost
password	String	the password required to login to the jumphost
adapter	String	must be either `"Cisco::IOS"` or `"Linux::Redhat"`

Python example:

from jsonrpc import JsonRpcProxy, JsonError

# netldHost should be defined as a variable containing the IP address/hostname of the NetLD server
netld_svc = JsonRpcProxy.fromHost(netldHost, "admin", "password")

network = "Default"

properties = {
   "enabled": "true",
   "host": "10.0.0.1",
   "username": "jsmith",
   "password": "mysecret",
   "adapter": "Linux::Redhat"
}

netld_svc.call('Jumphost.saveJumphost', network, properties)

netld_svc.call('Security.logoutCurrentUser')

Note: The jsonrpc functions are defined in jsonrpc.py in the SDK Examples/Python folder. Simply include that file in the same directory as your script.

Configuration¶

The configuration API provides the core functionality of retrieving configuration history and managing draft configurations.

Methods in this API return various “configuration objects” (e.g. ChangeLog) which encapsulate attributes of configuration history in Net LineDancer. These configuration objects are expressed in JSON format. The following JSON objects are returned by these APIs.

A Change object is expressed in JSON format seen here:

{
    "author": "smith",
    "path": "/running-config",
    "mimeType": "test-plain",
    "type": "A",
    "size": 4321,
    "previousChange": 1361241698,
    "revisionTime": 1361249887,
    "head": true,
    "hasMemo": false,
    "mappingType": "backup",
    "mappingId": "31"
}

Attribute	Type	Description
author	String	The netLD username who made the change that was recorded, if known. ‘n/a’ if not available.
path	String	The filesystem path of the configuration on the device
mimeType	String	The MIME-type of the configuration file. Possible values are ‘text/plain’, ‘application/octet-stream’ (binary), ‘application/x-tar’ (binary).
type	String	The kind of change recorded. Possible values are ‘M’ (modification to existing configuration), ‘A’ (addition of a never before seen configuration), ‘D’ (a deleted configuration)
size	Integer	The size of the configuration in bytes
previousChange	Integer	The timestamp of the previous configuration revision in milliseconds (in Unix Epoch time). Can be null.
revisionTime	Integer	The timestamp when the configuration was backed up, in milliseconds (in Unix Epoch time).
head	Boolean	“true” if this revision is the latest, “false” otherwise.
hasMemo	Boolean	“true” is there is a memo for this configuration, “false” otherwise.
mappingType	String	undocumented.
mappingId	String	undocumented.

A ChangeLog object is expressed in JSON format seen here:

{
    "timestamp": 2311232341,
    "changes": [<Change> objects]
}

Attribute	Type	Description
timestamp	Integer	The ‘Unix Epoch’ timestamp (in milliseconds) when the configuration was recorded
changes	Array	An array of `Change` objects, reflecting configurations that were captured at the same time (timestamp)

A PageData object is expressed in JSON format seen here:

{
    "offset": 0,
    "pageSize": 10,
    "total": 27,
    "changeLogs": [<ChangeLog> objects]
}

Attribute	Type	Description
offset	Integer	The starting `offset` in the results to begin retrieving `pageSize` number of `ChangeLog` objects.
pageSize	Integer	The maximum number of `ChangeLog` objects to retrieve in a single method call.
total	Integer	This value is set and retrieved from the server when an `offset` of zero (0) is passed. This indicates the total number of `ChangeLog` objects available.
changeLogs	Array	An array of `ChangeLog` objects

A Revision object is expressed in JSON format seen here:

{
    "path": "/running-config",
    "author": "n/a",
    "mimeType": "text/plain",
    "size": 4321,
    "previousChange": 1361241698,
    "content": <BASE64 ENCODED STIRING>
}

Attribute	Type	Description
path	String	The filesystem path of the configuration on the device
author	String	The netLD username who made the change that was recorded, if known. ‘n/a’ if not available.
mimeType	String	The MIME-type of the configuration file. Possible values are ‘text/plain’, ‘application/octet-stream’ (binary), ‘application/x-tar’ (binary).
size	Integer	The size of the configuration in bytes
previousChange	Integer	The timestamp of the previous configuration revision in milliseconds (in Unix Epoch time). Can be null.
content	String	The configuration file content, encoded in Base64 format

Configuration.retrieveSnapshotChangeLog¶

Retrieves the configuration history for the specified device.

Parameters¶

Parameter	Type	Description
network	String	Name of an existing network, e.g. “Default”
ipAddress	String	IPv4 or IPv6 address
pageData	JSON Object	A `PageData` object specifying the starting `offset` and `pageSize`.

Return: a `PageData` object¶

Sample Request JSON:¶

{
   "jsonrpc": "2.0",
   "method": "Configuration.retrieveSnapshotChangeLog",
   "params": {
              "network": "Default",
              "ipAddress": "192.168.0.254",
              "pageData": {
                           "offset": 0,
                           "pageSize": 10
                          }
             },
   "id": 1
}

The PageData object that is returned will contain an attribute called changeLogs, which is an array of ChangeLog objects. If the initial offset that is passed is zero (0), the returned PageData object will also contain a populated total attribute, telling you how many total results are available. By incrementing the offset by pageSize you can retrieve subsequent pages of results. When offset + pageSize is greater than or equal to total there are no more results available.

Sample Response JSON:¶

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": {
      "offset": 0,
      "pageSize": 10,
      "total": 1,
      "changeLogs": [
         {
            "changes":[
               {
                  "author": "brettw",
                  "path": "/running-config",
                  "mimeType": "text/plain",
                  "type": "A",
                  "size": 1601,
                  "previousChange": 1400922143000,
                  "revisionTime": 1410324618000,
                  "mappingType": "backup",
                  "mappingId": 4,
                  "hasMemo": false,
                  "file": false,
                  "head": true
               },
               {
                  "author": "brettw",
                  "path": "/startup-config",
                  "mimeType": "text/plain",
                  "type": "A",
                  "size": 1601,
                  "previousChange": 1400922143000,
                  "revisionTime": 1410324618000,
                  "mappingType": "backup",
                  "mappingId": 4,
                  "hasMemo": false,
                  "file": false,
                  "head": true
               }
            ],
            "timestamp": 1410324618000
         }
      ]
   }
}

Configuration.retrieveRevision¶

Retrieve a revision of a configuration for the specified device.

Parameters¶

Parameter	Type	Description
network	String	Name of an existing network, e.g. “Default”
ipAddress	String	IPv4 or IPv6 address
configPath	String	The path of the configuration file to retrieve. This should be the same value as the `path` attribute in a `Change` object.
timestamp	Integer	The timestamp (in Unix Epoch milliseconds) of the configuration to retrieve. This should be the same value as the `revisionTime` attribute in a `Change` object returned by `retrieveSnapshotChangeLog`. If timestamp is omitted, the latest revision is retrieved.

Return: a `Revision` object¶

Sample Request JSON:¶

{
   "jsonrpc": "2.0",
   "method": "Configuration.retrieveRevision",
   "params": {
              "network": "Default",
              "ipAddress": "192.168.0.254",
              "configPath": "/running-config",
              "timestamp": 1410324618000
             },
   "id": 1
}

Sample Response JSON:¶

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": {
      "lastChanged": 1410324618000,
      "path": "/running-config",
      "author": "brettw",
      "mimeType": "text/plain",
      "size": 1601,
      "prevChange": null,
      "runStart": 0,
      "content": <Base64 encoded string>
   }
}

Credentials¶

The credentials API provides the core functionality for device authentication credentials in Net LineDancer.

Methods in this API return various “credentials objects” (e.g. CredentialConfig) which encapsulate attributes of specific credentials in Net LineDancer. These configuration objects are expressed in JSON format.

A dynamic CredentialConfig object is expressed in JSON format seen here:

{
   "priority": 1,
   "addressSet": {
      "addresses": [
         "0.0.0.0/0"
      ]
   },
   "name": "LVI",
   "managedNetwork": "Default",
   "flat": false
}

Here is an example of a static CredentialConfig object. Note the empty addresses list and flat value of true:

{
   "priority": 0,
   "addressSet": {
      "addresses": [ ]
   },
   "name": "Static",
   "managedNetwork": "Default",
   "flat": true
}

Attribute	Type	Description
priority	Integer	A lower priority number indicates higher placement in the list of credential configurations. These credentials will be tried before others with a higher number.
addressSet	Object	A container for “addresses”. Consider this a “fixed” element.
addresses	String Array	An array of IP Addresses, IP Wildcards, and IP/CIDR expressions the a “dynamic” `CredentialConfig` applies to. This should be empty for static credential configurations.
name	String	The name of the `CredentialConfig` as seen in the user interface.
managedNetwork	String	The name of the network that this configuration applies to. If there are no user-created networks this value should be `Default`.
flat	Boolean	`true if` the `CredentialConfig` represents a “static” configuration, `false` if it is dynamic.

An example CredentialSet object is expressed in JSON format seen here:

{
   "name": "Lab Credentials #1",
   "username": "lvi",
   "password": "lvi",
   "enableUsername": "lvi",
   "enablePassword": "lvi",
   "roCommunityString": "public",
   "snmpUsername": "v3user",
   "snmpAuthPassword": "v3pass",
   "snmpPrivPassword": "v3priv",
   "priority": 0
}

Attribute	Type	Description
name	String	Name of the credential set. In the case of dynamic credentials this is any user defined name; for static credentials the name MUST be an IP address (IPv4 or IPv6).
username	String	The VTY username
password	String	The VTY password
enableUsername	String	The enable username
enablePassword	String	The enable password
roCommunityString	String	The SNMP read-only community string
snmpUsername	String	The SNMPv3 username
snmpAuthPassword	String	The SNMPv3 password
snmpAuthPriv	String	The SNMPv3 private password
priority	Integer	A lower priority number indicates higher placement in the list of credential sets. These credentials will be tried before others with a higher number. Inapplicable to static credentials

An example PageData object is expressed in JSON format seen here:

{
    "offset": 0,
    "pageSize": 10,
    "total": 27,
    "credentialSets": [<CredentialSet> objects]
}

Attribute	Type	Description
offset	Integer	The starting `offset` in the results to begin retrieving `pageSize` number of `CredentialSet` objects.
pageSize	Integer	The maximum number of `CredentialSet` objects to retrieve in a single method call.
total	Integer	This value is set and retrieved from the server when an `offset` of zero (0) is passed. This indicates the total number of `CredentialSet` objects available.
credentialSets	Array	An array of `CredentialSet` objects

Important Note¶

Maintaining session is important for this API to work correctly. The first invocation will assign to you a session ID by a cookie called JSESSIONID. Use this cookie to maintain session.

After commitEdits or discardEdits is invoked, you may discard this cookie.

Credentials.commitEdits¶

Commits edits made in this session.

Parameters: none¶

Return: nothing¶

Sample Request JSON:¶

{
   "jsonrpc": "2.0",
   "method": "Credentials.commitEdits",
   "params": {},
   "id": 1
}

Credentials.discardEdits¶

Discards edits made in this session.

Parameters: none¶

Return: nothing¶

Sample Request JSON:¶

{
   "jsonrpc": "2.0",
   "method": "Credentials.discardEdits",
   "params": {},
   "id": 1
}

Credentials.getCredentialConfig¶

Retrieves a single credential configuration CredentialConfig object.

Parameters¶

Parameter	Type	Description
network	String	Name of an existing network, e.g. “Default”
configName	String	Name of a dynamic or static credential configuration

Return: a `CredentialConfig` object¶

Sample Request JSON:¶

{
   "jsonrpc": "2.0",
   "method": "Credentials.getCredentialConfig",
   "params": {
              "network": "Default",
              "configName": "LogicVein"
             },
   "id": 1
}

Sample Response JSON:¶

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": {
      "priority": 2,
      "addressSet": {
         "addresses": [
            "0.0.0.0/0"
         ]
      },
      "name": "LogicVein",
      "managedNetwork": "Default",
      "flat": false
   }
}

Credentials.saveCredentialConfig¶

Save a single credential configuration. This method can be used to save a new configuration, or renaming an existing one. Note: after call this method you must call the commitEdits or discardEdits method. If you are making many changes, it is recommended that all changes are should be made before a final call to commitEdits.

Parameters¶

Parameter	Type	Description
network	String	Name of an existing network, e.g. “Default”
oldConfigName	String	When renaming a credential configuration, this value should be the “old” (original) name of the configuration, and object in the `credentialConfig` parameter should contain the new name. This can be `null` in all other cases.
credentialConfig	Object	A `CredentialConfig` object

Return: the updated `CredentialConfig` object¶

Sample Request JSON:¶

{
   "jsonrpc": "2.0",
   "method": "Credentials.saveCredentialConfig",
   "params": {
              "network": "Default",
              "oldConfigName": "LogicVein",
              "credentialConfig": {
                                   "priority": 1,
                                   "addressSet": {
                                                  "addresses": [ "0.0.0.0/0" ]
                                                 },
                                   "name": "LogicVein2",
                                   "managedNetwork": "Default",
                                   "flat": false
                                  }
             },
   "id": 1
}

Credentials.deleteCredentialConfig¶

Delete a single credential configuration. Note: after call this method you must call the commitEdits or discardEdits method. If you are making many changes, it is recommended that all changes are should be made before a final call to commitEdits.

Parameters¶

Parameter	Type	Description
network	String	Name of an existing network, e.g. “Default”
configName	String	Name of a dynamic or static credential configuration

Return: nothing¶

Sample Request JSON:¶

{
   "jsonrpc": "2.0",
   "method": "Credentials.deleteCredentialConfig",
   "params": {
              "network": "Default",
              "configName": "LogicVein"
             },
   "id": 1
}

Credentials.getCredentialSets¶

Get the credential sets associated with a specified credential configuration.

Parameters¶

Parameter	Type	Description
pageData	Object	A credentials page data object (see above)
network	String	Name of an existing network, e.g. “Default”
configName	String	Name of a dynamic or static credential configuration
ipOrCidr	String	Can be to search among static `CredentialSets` based on IP or IP/CIDR, can be “null”
sortColumn	String	Should be “null” for dynamic configurations, or “ipAddress” for static credential configurations
descending	Boolean	The sort order of the `CredentialSet` objects, only applicable to static configurations

Return: A `PageData` object containing a collection of `CredentialSet` objects¶

The PageData object that is returned will contain a property called credentialSets, which is an array of CredentialSet objects. If the initial offset that is passed is zero (0), the returned PageData object will also contain a populated total attribute, telling you how many total results are available. By incrementing the offset by pageSize you can retrieve subsequent pages of results. When offset + pageSize is greater than or equal to total there are no more results available.

Sample Request JSON:¶

{
   "jsonrpc": "2.0",
   "method": "Credentials.getCredentialSets",
   "params": {
              "pageData": {
                           "offset": 0,
                           "pageSize": 10,
                           "total": 0,
                           "credentialSets": [ ]
                          },
              "network": "Default",
              "configName": "LogicVein",
              "ipOrCidr": null,
              "sortColumn": "ipAddress",
              "descending": false
             },
   "id": 1
}

Sample Response JSON:¶

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": {
      "offset": 0,
      "pageSize": 10,
      "total": 2,
      "credentialSets": [
         {
            "name": "Lab Credentials #1",
            "username": "lvi",
            "password": "lvi",
            "enableUsername": "lvi",
            "enablePassword": "lvi",
            "roCommunityString": "public",
            "snmpUsername": "",
            "snmpAuthPassword": "",
            "snmpPrivPassword": "",
            "priority": 0
         },
         {
            "name": "Lab Credentials #2",
            "username": "test",
            "password": "test",
            "enableUsername": "test",
            "enablePassword": "test",
            "roCommunityString": "public",
            "snmpUsername": "test",
            "snmpAuthPassword": "test",
            "snmpPrivPassword": "test",
            "priority": 1
         }
      ]
   }
}

Static credential sets will look identical to dynamic credential sets with the exception that the name property will contain the IP address of the device that the credential set is associated with.

Credentials.saveCredentialSets¶

Save a collection of credential sets. Note: after call this method you must call the commitEdits or discardEdits method. If you are making many changes, it is recommended that all changes are should be made before a final call to commitEdits.

Parameters¶

Parameter	Type	Description
network	String	Name of an existing network, e.g. “Default”
configName	String	Name of a dynamic or static credential configuration
credentialSets	Array	An array of `CredentialSet` objects

Return: nothing¶

Sample Request JSON:¶

{
   "jsonrpc": "2.0",
   "method": "Credentials.saveCredentialSets",
   "params": {
              "network": "Default",
              "configName": "LogicVein",
              "credentialSets": [
                  {
                     "name": "Lab Credentials #1",
                     "username": "newUsername",
                     "password": "lvi",
                     "enableUsername": "newEnable",
                     "enablePassword": "lvi",
                     "roCommunityString": "public",
                     "snmpUsername": "",
                     "snmpAuthPassword": "",
                     "snmpPrivPassword": "",
                     "priority": 0
                  }
              ]
             },
   "id": 1
}

Credentials.deleteCredentialSets¶

Delete a collection of credential sets. Note: after call this method you must call the commitEdits or discardEdits method. If you are making many changes, it is recommended that all changes are should be made before a final call to commitEdits.

Parameters¶

Parameter	Type	Description
network	String	Name of an existing network, e.g. “Default”
configName	String	Name of a dynamic or static credential configuration
credentialSets	Array	An array of `CredentialSet` objects

Return: nothing¶

Sample Request JSON:¶

{
   "jsonrpc": "2.0",
   "method": "Credentials.deleteCredentialSets",
   "params": {
              "network": "Default",
              "configName": "LogicVein",
              "credentialSets": [
                  {
                     "name": "Old Credentials #1",
                     "username": "lvi",
                     "password": "lvi",
                     "enableUsername": "newEnable",
                     "enablePassword": "lvi",
                     "roCommunityString": "public",
                     "snmpUsername": "",
                     "snmpAuthPassword": "",
                     "snmpPrivPassword": "",
                     "priority": 0
                  },
                  {
                     "name": "Old Credentials #2",
                     "username": "test",
                     "password": "test",
                     "enableUsername": "test",
                     "enablePassword": "test",
                     "roCommunityString": "public",
                     "snmpUsername": "",
                     "snmpAuthPassword": "",
                     "snmpPrivPassword": "",
                     "priority": 1
                  }
              ]
             }
   "id": 1
}

Scheduler¶

The scheduler API provides access to job management, scheduling and execution. Job types include tools, configuration backup, Smart Changes, and reports.

Scheduler.runNow¶

Execute a job defined by the specified JobData.

Parameters¶

Parameter	Type	Description
jobData	JSON Object	A `JobData` object

Return: an `ExecutionData` object.¶

Scheduler.saveJob¶

Save (or replace) the job defined by the specified JobData.

Parameters¶

Parameter	Type	Description
jobData	JSON Object	A `JobData` object

Return: the `JobData` object with `jobId` property populated.¶

Scheduler.deleteJob¶

Delete a job by ID.

Parameters¶

Parameter	Type	Description
jobId	Integer	The ID of the Job

Return: `true` if the Job was deleted successfully, `false` otherwise¶

Scheduler.getJob¶

Get the JobData for the job with the specified ID.

Parameters¶

Parameter	Type	Description
jobId	Integer	The ID of the Job

Return: a `JobData` object.¶

Scheduler.searchJobs¶

Get a JobPageData object containing “shallow” JobData objects. These JobData objects do not contain jobParameters and cannot directly be used to execute jobs via the runNow() method. However, the job ID can be used to obtain a full JobData object suitable for execution directly by the runNow() method.

Parameters¶

Parameter	Type	Description
pageData	JSON Object	A `JobPageData` object specifying the starting offset and pageSize.
networks	Array	An array of managed network names to search for jobs in.
sortColumn	String	A string indicating the `JobData` object attribute the results should be sorted by, null for default.
descending	Boolean	A boolean flag indicating whether results should be sorted in descending or ascending order.

Return: a `JobPageData` object containing search results¶

Scheduler Objects¶

JobData¶

Field	Type	Description
jobId	Integer	The job ID (read-only)
jobName	String	The name of the job
description	String	The description of the job
managedNetworks	Array	An array of managed network names this job set is available in
jobType	String	One of the pre-defined NetLD job types (see below)
jobParameters	Map	A map (hash) of job parameter name/value pairs that are specific to each jobType (see below)
isAccessLimited	Boolean	`true` if the caller has limited visibility to the networks defined for this job (read-only)
isGlobal	Boolean	`true` if the specified job is a “global” (aka system) job (read-only)

JobPageData¶

Field	Type	Description
offset	Integer	The starting offset in the results to begin retrieving pageSize number of `JobData` objects.
pageSize	Integer	The maximum number of `JobData` objects to retrieve in a single method call.
total	Integer	This value is set and retrieved from the server when an offset of zero (0) is passed. This indicates the total number of `JobData` objects available. (read-only)
jobData	Array	An array of `JobData` objects

ExecutionData¶

Field	Type	Description
id	Integer	The execution ID
jobName	String	The name of the job
managedNetworks	Array	An array of managed network names the job was associated with
executor	String	The user name of the user who executed the job
startTime	64-bit Integer	The start time of the job as a Unix epoch value
endTime	64-bit Integer	The end time of the job as a Unix epoch value
completionState	Integer	0=normal, 1=cancelled, 2=misfired (schedule missed)
status	String	One of: “OK”, “WARN”, “ERROR”, “ABORT”
isPartialView	Boolean	`true` if the caller has limited visibility to the networks defined for this job
isGlobal	Boolean	`true` if the specified job is a “global” (aka system) job

Job Types¶

Type Name	Type Description
“Discover Devices”	Network device discovery.
“Backup Configuration”	Network device configuration backup.
“Telemetry”	Network device neighbor information collection.
“Script Tool Job”	Pre-definied read/write tool execution.
“Bulk Update”	SmartChange execution.
“Report”	Pre-definied report execution.

Job Parameters (per Job Type)¶

All job parameter names and values are UTF-8 strings. Even “boolean” and “integer” values are represented as strings such as “true” or “5432”.

“Discover Devices”¶

Name	Type	Value Description
communityStrings	String	Additional SNMP community string or comma-separated list of strings
boundaryNetworks	String	Comma-separated list of discovery boundary networks (CIDR)
crawl	String	A “boolean” value indicating whether the discovery should use neighbor/peer information to discover additional devices
includeInventory	String	A “boolean” value indicating whether the discovery should automatically include current inventory devices. This option is only meaningful when “crawl” is also set to “true”
addresses	String	A comma-separated list of IP address “shapes” to include in the discovery. See below.

Plugins¶

The plugins API provides access to tool job execution results.

NOTE: This API has significant and incompatible changes in the next major release. The name of this service endpoint is likely to change. You will need to update any scripts that use these APIs.

Plugins.getExecutionDetails¶

Get the list of ToolRunDetails, one per device, for the given scheduler execution ID. Note that currently only the SmartChange (“bulk update”) job contains accessible tool execution records.

Parameters¶

Parameter	Type	Description
executionId	Integer	The execution ID of the tool job.

Return: an array of `ToolRunDetails` objects or `null`¶

Plugins Objects¶

ToolRunDetails¶

Field	Type	Description
id	Integer	The ID of the tool detail record, used to retrieve the text of the detail from the detail URL endpoint (see below)
ipAddress	String	The IP address of the device of this detail record
managedNetwork	String	The name of the network in which the device is defined
executionId	Integer	The ID of the job execution
error	String	An error string if one exists, or null
gridData	String	A CSV of execution values, one row per device
startTime	64-bit Integer	The start time of the job as a Unix epoch value
endTime	64-bit Integer	The end time of the job as a Unix epoch value.

Some tools return all of their data in the gridData attribute, others contains additional textual output from the device, available from the URL endpoint below.

Individual output detail for each device in an execution is available through the following URL endpoint:

https://<host>/servlet/pluginDetail?executionId=<executionId>&recordId=<id>

Where <host> is the NetLD server, <executionId> is the job execution ID, and <id> is the individual record ID contained in the ToolRunDetails record for a specific device.

Typically, the Plugins.getExecutionDetails API is used to obtain a list of ToolRunDetails records, and then for each record (one per device) the URL endpoint is accessed to obtain the textual output from the device.

See the Python example scripts in the SDK for example uses.

Compliance¶

The compliance API provides access to compliance policies, rules, and violation information.

Compliance Service Methods¶

Compliance.getRuleSet¶

Get the compliance ruleset for the given ID

Parameters¶

Parameter	Type	Description
ruleSetId	Integer	The ID of the desired RuleSet object

Return: the `RuleSet` object or `null`¶

Compliance.getPolicies¶

Get the list of policies in a given managed networks.

Parameters¶

Parameter	Type	Description
network	String	The managed network

Return: an array of `PolicyInfo` objects¶

Compliance.getPolicy¶

Get the policy definition by ID.

Parameters¶

Parameter	Type	Description
policyId	Integer	The ID of the desired policy

Return: a `Policy` object or `null`¶

Compliance.getViolationsForDevice¶

Get the list of current violations for a given device.

Parameters¶

Parameter	Type	Description
network	String	The managed network of the device
ipAddress	String	The IP address of the device

Return: an array of `Violation` objects¶

Compliance.getViolationsForPolicy¶

Get the list of current violations for a given policy.

Parameters¶

Parameter	Type	Description
policyId	Integer	The ID of the desired violations policy

Return: an array of `Violation` objects¶

Compliance Objects¶

RuleSet¶

Field	Type	Description
ruleSetId	Integer	The rule set ID
ruleSetName	String	The name of the rule set
adapterId	String	The Adapter ID of the device
configPath	String	The device configuration this rule applies to
ruleSetXml	String	The rule set definition
networks	Array	An array of managed networks this rule set is available for
readOnly	Boolean	A boolean flag indicating whether or not this rule set is editable

PolicyInfo¶

Field	Type	Description
policyId	Integer	The policy’s ID
policyName	String	The name of the policy
network	String	The managed network the policy is in
enabled	Boolean	A boolean flag indicating whether or not this policy is enabled
coveredDevice	Integer	The number of devices covered by this policy
violatingDevices	Integer	The number of devices in violation of this policy

Policy¶

Field	Type	Description
policyId	Integer	The policy’s ID
policyName	String	The name of the policy
network	String	The managed network the policy is in
adapterId	String	The Adapter ID of the device
configPath	String	The device configuration this policy applies to
resolutionScheme	String	A single scheme name or comma-separated list of scheme names
resolutionData	String	The query associated with the scheme(s) specified

Violation¶

Field	Type	Description
policyId	Integer	The ID of the Policy in violation
ruleSetId	Integer	The ID of the RuleSet in violation
ipAddress	String	The IP Address of the device in violation
network	String	The managed network of the device in violation
message	String	The violation message
severity	Integer	The violation severity. 1 for WARNING, 2 for ERROR

Telemetry¶

The telemetry API provides the core functionality of retrieving device neighbor information from the inventory.

See the Telemetry Objects section for a description of the various objects consumed and returned by these APIs.

Telemetry.getArpTable¶

Retrieves an entire ARP table for the given device.

Parameters¶

Parameter	Type	Description
pageData	JSON Object	A `PageData` object specifying the starting `offset` and `pageSize`.
managedNetwork	String	Name of an existing network, e.g. “Default”
ipAddress	String	IPv4 or IPv6 address
sort	String	A string indicating the `ArpTableEntry` object attribute the results should be sorted by, null for default
descending	Boolean	A boolean flag indicating whether results should be sorted in descending or ascending order.

Return: A `ArpPageData` object of the last retreived ARP table.¶

Telemetry.getArpEntries¶

Retrieves all ARP entries from all devices where the IP Address of the ARP entry is contained in the provided networkAddress.

Parameters¶

Parameter	Type	Description
pageData	JSON Object	A `PageData` object specifying the starting `offset` and `pageSize`.
networkAddress	String	The address to get entries on, e.g. ‘10.100.0.0/16’
sort	String	A string indicating the `DeviceArpTableEntry` object attribute the results should be sorted by, null for default
descending	Boolean	A boolean flag indicating whether results should be sorted in descending or ascending order.
networks	Array	An array of managed network names to search

Return: A `DeviceArpPageData` object.¶

Telemetry.getMacTable¶

Retrieves an entire MAC forwarding table for the given device.

Parameters¶

Parameter	Type	Description
pageData	JSON Object	A `PageData` object specifying the starting `offset` and `pageSize`.
managedNetwork	String	Name of an existing network, e.g. “Default”
ipAddress	String	IPv4 or IPv6 address
sort	String	A string indicating the `MacTableEntry` object attribute the results should be sorted by, null for default
descending	Boolean	A boolean flag indicating whether results should be sorted in descending or ascending order.

Return: A `MacPageData` object.¶

Telemetry.getNeighbors¶

Retrieves routing (OSPF, EIGRP, BGP) and discovery protocol neighbors (CDP, NDP) for the given device.

Parameters¶

Parameter	Type	Description
managedNetwork	String	Name of an existing network, e.g. “Default”
ipAddress	String	IPv4 or IPv6 address

Returns: An Array of `Neighbor` objects.¶

Telemetry.findSwitchPort¶

Given a host IP, MAC address or hostname, find the switch port that the device is physically plugged into.

Parameters¶

Parameter	Type	Description
host	String	the host as a MAC address, and IP address or a hostname
networks	Array	An array of managed network names to search

Return: A `SwitchPortResult` object.¶

Telemetry Objects¶

ArpPageData¶

Attribute	Type	Description
offset	Integer	The starting `offset` in the results to begin retrieving `pageSize` number of `ArpTableEntry` objects. This value is required when `ArpPageData` is used as a parameter.
pageSize	Integer	The maximum number of `ArpTableEntry` objects to retrieve in a single method call. This value is required when `ArpPageData` is used as a parameter.
total	Integer	This value is set and retrieved from the server when an `offset` of zero (0) is passed. This indicates the total number of `ArpTableEntry` objects available. This value is ignored when `ArpPageData` is used as a parameter.
arpEntries	Array	An array of `ArpTableEntry` objects. This value is ignored when `ArpPageData` is used as a parameter.

ArpTableEntry¶

Attribute	Type	Description
ipAddress	String	The IP Address
interfaceName	String	The interface name
macAddress	String	The MAC address

DeviceArpPageData¶

Attribute	Type	Description
offset	Integer	The starting `offset` in the results to begin retrieving `pageSize` number of `DeviceArpTableEntry` objects. This value is required when `DeviceArpPageData` is used as a parameter.
pageSize	Integer	The maximum number of `DeviceArpTableEntry` objects to retrieve in a single method call. This value is required when `DeviceArpPageData` is used as a parameter.
total	Integer	This value is set and retrieved from the server when an `offset` of zero (0) is passed. This indicates the total number of `DeviceArpTableEntry` objects available. This value is ignored when `DeviceArpPageData` is used as a parameter.
arpEntries	Array	An array of `DeviceArpTableEntry` objects. This value is ignored when `DeviceArpPageData` is used as a parameter.

DeviceArpTableEntry¶

Attribute	Type	Description
device	String	The IP Address of the device that the ARP entry was found on.
managedNetwork	String	The managed network of the device that the ARP entry was found on.
ipAddress	String	The IP Address in the ARP entry.
macAddress	String	The MAC Address in the ARP entry.
interfaceName	String	The interface name in the ARP entry.

MacPageData¶

Attribute	Type	Description
offset	Integer	The starting `offset` in the results to begin retrieving `pageSize` number of `MacTableEntry` objects. This value is required when `MacPageData` is used as a parameter.
pageSize	Integer	The maximum number of `MacTableEntry` objects to retrieve in a single method call. This value is required when `MacPageData` is used as a parameter.
total	Integer	This value is set and retrieved from the server when an `offset` of zero (0) is passed. This indicates the total number of `MacTableEntry` objects available. This value is ignored when `MacPageData` is used as a parameter.
macEntries	Array	An array of `MacTableEntry` objects. This value is ignored when `MacPageData` is used as a parameter.

MacTableEntry¶

Attribute	Type	Description
port	String	The port in the MAC table.
vlan	String	The VLAN in the MAC table.
macAddress	String	The MAC Address in the MAC table.

Neighbor¶

Attribute	Type	Description
protocol	String	The neighbor protocol (OSPF, BGP, CDP, etc)
ipAddress	String	The IP Address of the neighbor
localInterface	String	The local interface that the neighbor was seen on.
remoteInterface	String	The interface on the neighbor
otherId	String	The neighbors ‘ID’

SwitchPortResult¶

Attribute	Type	Description
hostIpAddress	String	The target IP Address
hostMacAddress	String	The MAC address of the host
arpEntry	DeviceArpTableEntry	The ARP entry that the host was found on.
macEntry	DeviceMacTableEntry	The MAC table entry that the host was found on.
error	Integer	An error code. 0 - no error1 - unable to resolve host2 - unable to find IP in an ARP/NDP table3 - unable to find the MAC address in a forwarding table

Terminal Proxy¶

The Terminal Proxy API provides the core functionality for auto-login to devices as well as access to terminal proxy session histories.

One-time Authentication Token¶

Before a terminal proxy session to a device can proceed through the server, a one-time use authentication token must be created. The authentication token can be created by calling the createTemporaryAuthenticationToken method on the Security service.

Security.createTemporaryAuthenticationToken¶

Creates a one-time use authentication token.

Parameters¶

Parameter	Type	Description
attributes	JSON Object	A JSON “map” that contains required attributes documented below

The attributes parameter is a JSON map containing two key/value pairs:

Key	Value
targetDevice	the IP address of the target device and its network name in the format ipAddress@networkName
targetProtocol	either “SSH” or “Telnet”

Example of the attributes map as expressed in JSON:

{
   "targetDevice": "10.0.0.1@Default",
   "targetProtocol": "SSH"
}

Return: An authentication one-time use token as a string.¶

Python example:

from jsonrpc import JsonRpcProxy, JsonError

# netldHost should be defined as a variable containing the IP address/hostname of the NetLD server
netld_svc = JsonRpcProxy.fromHost(netldHost, "admin", "password")

attributes = {
   "targetDevice": "10.0.0.1@Default",
   "targetProtocol": "SSH"
}

token = netld_svc.call('Security.createTemporaryAuthenticationToken', attributes)

print "Token: " + token

Note: The authentication token expires 30 seconds after creation, and therefore must be used within that time.

Note: The jsonrpc functions are defined in jsonrpc.py in the SDK Examples/Python folder. Simply include that file in the same directory as your script.

Complete Flow¶

Once an authentication token is obtained, you are free to initiate an SSH connection to the server. Note that SSH is used to communitcate with the server regardless of the protocol (SSH or Telnet) used to connect to the target device.

CLI Example:

ssh <token>@<netldHost>:2222

Where <token> is the token obtained via the API above, and <netldHost> is the IP address or hostname of the server.

Some SSH clients, notably OpenSSH, accept the connection information in the form of a URI:

ssh ssh://<token>@<netldHost>:2222

When the session connects, if the user who created the token (“admin” in the example above) is authorized to “auto-login” to the device then the server will guide the login process through the auto-login procedure and leave the session connected at the target device command prompt immediately following the login procedure.

Terminal Proxy Log Search and Retrieval¶

The TermLogs service provides search capability over the collection of terminal proxy logs stored in the system.

TermLogs.search¶

Search supports many criteria, and the criteria can be combined to perform powerful searches.

Parameter	Type	Description
scheme	String	A single scheme name, or comma-separated list of scheme names (see table below)
query	String	The query associated with the scheme(s) specified. If there are multiple schemes specified, the query parameter should contain new-line (n) characters between each query string
sortColumn	String	A string indicating the `Device` object attribute the results should be sorted by
descending	Boolean	A boolean flag indicating whether results should be sorted in descending or ascending order

The scheme parameter is a single value, or a comma separated list of search schemes from the following table:

Scheme	Description
user	The username of a specific user for which to find logs, can include leading or trailing wildcards
session	A time value in which the log occurred. ‘24h’, ‘7d’, ‘30d’, or a date range e.g. ‘2020-01-00T00:00:00/2020-05-15T08:15:30’
since	A start time value in the format of ‘2020-05-15T08:15:30’
network	A single value, or CSV of network names in which target devices must reside
target	The specific IP address of the device that was the target of the session
client	The specific IP address of the client that was the source of the session
hostname	The hostname of the device that was the target of the session, can include leading or trailing wildcards
text	Specific text that must appear within the terminal log

The query parameter defines the query criteria to be used and is in association with the schemes defined by the scheme parameter. For example, if you wish to search based on scheme user and hostname you would specify a scheme parameter of “user,hostname”, and a query parameter of “williamntokyo*”. Note the newline character between the user query value and the hostname query value.

Return: An array of `TermLogSearchResult` objects¶

Python example:

from jsonrpc import JsonRpcProxy, JsonError

# netldHost should be defined as a variable containing the IP address/hostname of the NetLD server
netld_svc = JsonRpcProxy.fromHost(netldHost, "admin", "password")

results = netld_svc.call('TermLogs.search', 'user,session', "william\n24h", 'sessionStart', False)

for record in results:
   print '{0}, {1}, {2}-{3}, {4}'
      .format(record['logId'], record['username'], record['sessionStart'], record['sessionEnd'], record['ipAddress'])

Note: The jsonrpc functions are defined in jsonrpc.py in the SDK Examples/Python folder. Simply include that file in the same directory as your script.

Terminal Proxy Objects¶

TermLogSearchResult¶

Field	Type	Description
logId	Integer	The internal log identifier.
username	String	The username of the user who connected to the device.
sessionStart	Date	The start time of the terminal session.
sessionEnd	Date	The end time of the terminal session.
ipAddress	String	The IPv4 or IPv6 address of the device.
clientIpAddress	String	The IPv4 or IPv6 address of the client computer.
hostname	String	The hostname of the device.
managedNetwork	String	The name of the managed network that the device resides in.
protocol	String	The protocol used between the server and target device.

Individual Terminal Log Retrieval¶

Once a TermLogSearchResult record of a terminal proxy log has been obtained via search, the content of a desired terminal log can be retrieved via a simple HTTP GET request.

Required HTTP URL parameters:

Field	Value
op	“content”, constant string
stripXml	“true”, constant string
sessionStart	The `sessionStart` value from a `TermLogSearchResult` record
ipAddress	The `ipAddress` value from a `TermLogSearchResult` record
managedNetwork	The `managedNetwork` value from a `TermLogSearchResult` record

A Python example, in continuation of the example above:

import urllib2
...

opener = urllib2.build_opener(netld_svc._cookie_processor, netld_svc._https_handler)
url = 'https://{0}/servlet/termlog?op=content&stripXml=true&sessionStart={1}&ipAddress={2}&managedNetwork={3}'
   .format(netld_svc._host, record['sessionStart'], record['ipAddress'], record['managedNetwork'])
resp = opener.open(url)
respdata = str(resp.read())

Bridges¶

The bridges API provides the functionality of managing the smart bridge settings.

Objects¶

Bridges¶

Attribute	Type	Description
bridgeId	Integer	The database ID of the bridge
name	String	The SmartBridge name
hostOrIp	String	The host or IP address of the smart bridge
port	Integer	The port to connect to the smart bridge on.
inbound	Boolean	True if the smart bridge initiates the connection to the core server, false if the core server initiates the connection to the smart bridge.
token	String	The authentication token used for connecting to the smart bridge.

Methods¶

Bridges.defineBridge¶

Create a new network bridge within the system.

Parameters¶

Parameter	Type	Description
bridgeName	String	The SmartBridge name
hostOrIp	String	The host or IP address of the smart bridge
port	String	The port to connect to the smart bridge on.
inbound	Boolean	True if the smart bridge initiates the connection to the core server, false if the core server initiates the connection to the smart bridge.
token	String	The authentication token used for connecting to the smart bridge.

Return: void¶

Bridges.getBridge¶

Get a bridge by name.

Parameters¶

Parameter	Type	Description
bridgeName	String	The SmartBridge name

Return: A `Bridge` object¶

Bridges.getAllBridges¶

Get all of the defined bridges.

Parameters¶

None

Return: An array of `Bridge` objects¶

Bridges.deleteBridge¶

Delete the bridge definition with the specified name

Parameters¶

Parameter	Type	Description
bridgeName	String	The SmartBridge name

Return: void¶

Bridges.updateBridge¶

Get a bridge by name.

Parameters¶

Parameter	Type	Description
bridge	Bridge	The bridge definition to update

Return: void¶

Zero Touch (including Cisco PnP)¶

The zerotouch API provides the core functionality of retrieving Zero Touch post-device deployment status.

See the ZeroTouch Objects section for a description of the various objects consumed and returned by these APIs.

ZeroTouch.searchHistory¶

Retrieves an entire ARP table for the given device.

Parameters¶

Parameter	Type	Description
queryString	String	A device identifier, including a possibly trailing wildcard character (), or empty (zero length string) forall*
pageData	PageData	A `PageData` object defining the offset where retrieval should begin and page size
sortColumn	String	A string indicating the `ZcHistory` object attribute the results should be sorted by
descending	Boolean	A boolean flag indicating whether results should be sorted in descending or ascending order

Return: A `PageData` object¶

The PageData object that is returned will contain an attribute called histories, which is an array of ZcHistory objects. If the initial offset that is passed is zero (0), the returned PageData object will also contain a populated total attribute, telling you how many total results are available. By incrementing the offset by pageSize you can retrieve subsequent pages of results. When offset + pageSize is greater than or equal to total there are no more results available.

Sample Request JSON:¶

{
   "jsonrpc": "2.0",
   "method": "ZeroTouch.searchHistory",
   "params": {
       "queryString": "",
       "pageData": {
            "offset": 0,
            "pageSize": 100
       },
       "sortColumn": "statusTime",
       "descending": true
   },
   "id": 1
}

Sample Response JSON:¶

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "offset": 0,
        "pageSize": 100,
        "total": 1,
        "histories": [
            {
                "deploymentId": "zhe9njl3e5g0",
                "deviceIdent": "FNC90934C",
                "address": "192.168.10.143",
                "statusTime": "2020-11-05T13:15:30Z",
                "statusCode": "STATUS_CODE_SUCCESS",
                "lineNumber": 0,
                "templateName": "Cisco 1841",
                "statusMessage": "STATUS_CODE_SUCCESS"
            }
        ]
    }
}

ZcHistory¶

Field	Type	Description
deploymentId	String	The internal deployment ID used during provisioning
deviceIdent	String	The identifier (usually serial number) provided by the device requesting provisioning
address	String	The IP address where the request originated. Could be the device or an intermediary relay agent
statusTime	Date	A W3C formatted date/time string (in the UTC timezone)
statusCode	String	A value from the status code table below
lineNumber	Integer	The line number of a configuration line error rejected by the device, or 0
templateName	String	The name of the ZeroTouch template used for provisioning
statusMessage	String	An error message from the device, or one of “STATUS_CODE_SUCCESS” or “STATUS_CODE_FAILURE”

Status codes (for ``ZcHistory` statusCode above)¶

Status Codes
NETLD_DEPLOY
NETLD_RECOVERY
NETLD_NO_CONFIG
STATUS_CODE_SUCCESS
STATUS_CODE_FAILURE

PageData¶

Attribute	Type	Description
offset	Integer	The starting `offset` in the results to begin retrieving `pageSize` number of `Device` objects. This value is required when `PageData` is used as a parameter.
pageSize	Integer	The maximum number of `Device` objects to retrieve in a single method call. This value is required when `PageData` is used as a parameter.
total	Integer	This value is set and retrieved from the server when an `offset` of zero (0) is passed. This indicates the total number of `Device` objects available. This value is ignored when `PageData` is used as a parameter.
histories	Array	An array of `ZcHistory` objects. This value is ignored when `HistoryPageData` is used as a parameter and should be empty for wire efficiency.

Incidents¶

The incidents API provides the core functionality of searching ThirdEye incidents.

See the Incident Objects section for a description of the various objects consumed and returned by these APIs.

Incident.search¶

The Incidents.search method is the fundemental way of retrieving incidents from the server. Search supports many criteria, and the criteria can be combined to perform powerful searches.

Parameter	Type	Description
pageData	Object	A `PageData` object defining the offset where retrieval should begin and page size
queries	Array	An array of query strings defining the search criteria
sortColumn	String	A string indicating the `Incident` object attribute the results should be sorted by
descending	Boolean	A boolean flag indicating whether results should be sorted in descending or ascending order

Within the queries array, each query string contains a schema, followed by an equals sign, followed by the value of the search parameter.

Example: ["severity=CRITICAL", "hostname=web"]

Scheme	Description
incidentId	The internal ID of the Incident
severity	The severity of the Incident
status	The status of the Incident
hostname	The hostname or hostname prefix of a device associated with the Incident
ipAddress	The IP address, or CIDR mask, of a device(s) associated with the Incident
start	Search Incidents where the specified value is >= the `modified` timestamp
end	Search Incidents where the specified value is <= the `created` timestamp

Return: A `PageData` object¶

The PageData object that is returned will contain an attribute called incidents, which is an array of Incident objects. If the initial offset that is passed is zero (0), the returned PageData object will also contain a populated total attribute, telling you how many total results are available. By incrementing the offset by pageSize you can retrieve subsequent pages of results. When offset + pageSize is greater than or equal to total there are no more results available.

Sample Request JSON:¶

{
   "jsonrpc": "2.0",
   "method": "Incidents.search",
   "params": {
        "pageData": {
            "offset": 0,
            "pageSize": 100
        },
       "queries": ["severity=CRITICAL", "hostname=web"],
       "sortColumn": "modified",
       "descending": true
   },
   "id": 1
}

Incident.getIncidentById¶

The Incidents.getIncidentById method returns an Incident object as described below, or null if the requested Incident does not exist.

Parameter	Type	Description
incidentId	Integer	The internal ID of the Incident

Return: An `Incident` object or null¶

Incident Objects¶

Incident¶

Field	Type	Description
incidentId	Int	The internal Incident ID of the device
summary	String	The generated or edited summary of the Incident
severity	String	NONE,DEBUG,INFORMATIONAL,NOTICE,WARNING,ERROR,CRITICAL,ALERT,EMERGENCY
priority	String	LOW,MEDIUM,HIGH
status	String	OPEN,RESOLVED,WORKING,DEFERRED
resolution	String	PENDING,FIXED,EXPECTED,TRANSIENT
assignee	String	The username of the user assigned to the Incident
clearState	String	NOT_CLEARED,CLEARING,CLEARED
created	Date	The timestamp of when the Incident was created
modified	Date	The timestamp of when the Incident was last modified
resolved	Date	The timestamp of when the Incident was resolved
nodes	Int	The number of nodes associated with the Incident
triggers	Int	The number of triggers associated with the Incident
occurrences	Int	The number of occurrences associated with the Incident

PageData¶

Attribute	Type	Description
offset	Integer	The starting `offset` in the results to begin retrieving `pageSize` number of `Incident` objects. This value is required when `PageData` is used as a parameter.
pageSize	Integer	The maximum number of `Incident` objects to retrieve in a single method call. This value is required when `PageData` is used as a parameter.
total	Integer	This value is set and retrieved from the server when an `offset` of zero (0) is passed. This indicates the total number of `Incident` objects available. This value is ignored when `PageData` is used as a parameter.
incidents	Array	An array of `Incident` objects. This value is ignored when `PageData` is used as a parameter.

Device Adapter IDs¶

Adapter ID
Nortel::Accelar
A10::AX1000
Accedian::NetworkDevice
Adtran::NetVanta
Alaxala::AXS
Alcatel::Omniswitch
Alcatel::TiMOS
AlliedTelesis::AlliedWare
AlliedTelesis::FS900M
AlliedTelesis::Series8700SL
AlliedTelesyn::Rapier
Alteon::AD3
Anritsu::PureFlowGS
APC::SmartUPS
Arista::EOS
Aruba::ArubaCX
Aruba::ArubaOS
Avocent::ACS
BlueCoat::ProxySG
Brocade::FabricOS
Brocade::NetworkOS
Cabletron::Switch
CEC::NetworkDevice
Century::NXR
CheckPoint::SecurePlatform
CheckPoint::vpn1edge
Cisco::ACI
Cisco::ACNS
Cisco::ACSW
Cisco::Airespace
Cisco::ArrowPoint
Cisco::CatOS
Cisco::CS500
Cisco::GSS
Cisco::IE
Cisco::IOS
Cisco::Linksys
Cisco::LocalDirector
Cisco::MDS
Cisco::Nexus
Cisco::SCE
Cisco::SCELite
Cisco::SecurityAppliance
Cisco::SmallBusiness
Cisco::Three005
Cisco::VxWorks
Cisco::WAAS
Cisco::WLSE
Citrix::NetScaler
Dell::PowerConnect
DLINK::DGS
Dyden::MediaConverter
Enterasys::Matrix
Enterasys::SecureStack
Enterasys::SSR
Enterasys::VerticalHorizon
Extreme::Convergence
Extreme::ERS
Extreme::Switch
Extreme::VSP
Extreme::XOS
F5::BigIP
F5::ThreeDNS
Fortinet::FortiGate
Foundry::EdgeIron
Foundry::FastIron
Fujitsu::CFabric
Fujitsu::Ipcom
Fujitsu::SRS
Furukawa::FX
Generic::SNMP
H3C::Switch
Hirschmann::RailSwitch
Hitachi::Apresia
Hitachi::ApresiaLight
Hitachi::GMC
HP::ProCurve
HP::ProcurveM
Huawei::VRP
Infoblox::NIOS
InfobloxTest0::NIOS
InfobloxTest1::NIOS
Juniper::DX
Juniper::JUNOS
Juniper::MSS
Juniper::ScreenOS
Kemp::LoadMaster
Linux::Cumulus
Linux::Opengear
Linux::RedHat
MikroTik::RouterOS
Mitsubishi::ST
NEC::IX2025
NEC::PF
NEC::SpectralWave
NEC::WA1020
Netgear::Switch
Nexans::Switch
Nortel::BayRS
Nortel::BayStack
Nortel::Contivity
Nortel::Passport
Nortel::Passport1600
Nortel::Tiara
Paloalto::PA500
Panasonic::Switch
Pica8::PicOS
Riverbed::Steelhead
Ruckus::ZoneDirector
SonicWALL::SonicOS
TPLink::Switch
Vyatta::OFR
WatchGuard::Fireware
YAMAHA::RT107e

JSON-RPC¶

Inventory¶

Inventory.createDevice¶

Parameters¶

Return: an error message or null¶

Inventory.deleteDevice¶

Parameters¶

Return: null¶

Inventory.getDevice¶

Parameters¶

Return: Device object or null¶

Inventory.updateDevice¶

Return: null¶

Python Example:¶

Inventory.updateDevices¶

Return: null¶

Inventory.search¶

Return: A PageData object¶

Sample Request JSON:¶

Sample Response JSON:¶

Sample Request JSON combining two search schemes:¶

Inventory Objects¶

Device¶

PageData¶

Inventory.getDeviceHardware¶

Parameters¶

Return: list of Hardware Objects¶

Networks¶

Methods¶

Networks.defineManagedNetwork¶

Parameters¶

Return: void¶

Networks.getManagedNetwork¶

Parameters¶

Return: A ManagedNetwork object¶

Networks.getManagedNetworkNames¶

Parameters¶

Return: An array of Strings¶

Networks.getAllManagedNetworks¶

Parameters¶

Return: An array of ManagedNetwork objects¶

Networks.deleteManagedNetwork¶

Parameters¶

Return: void¶

Networks.updateManagedNetwork¶

Parameters¶

Return: void¶

Networks.getManagedNetworksByBridge¶

Parameters¶

Return: An array of ManagedNetwork objects¶

Objects¶

ManagedNetwork¶

Jumphosts¶

Methods¶

Jumphost.getJumphostForNetwork¶

Parameters¶

Return: a hashmap (key/value pairs) of jumphost settings, or null if none exist for the specified network¶

Jumphost.saveJumphost¶

Parameters¶

Return: void¶

Configuration¶

Configuration.retrieveSnapshotChangeLog¶

Parameters¶

Return: a PageData object¶

Sample Request JSON:¶

Sample Response JSON:¶

Configuration.retrieveRevision¶

Parameters¶

Return: a Revision object¶

Sample Request JSON:¶

Sample Response JSON:¶

Credentials¶

Important Note¶

Credentials.commitEdits¶

Parameters: none¶

Return: nothing¶

Sample Request JSON:¶

Credentials.discardEdits¶

Parameters: none¶

Return: nothing¶

Return: an error message or `null`¶

Return: `null`¶

Return: `Device` object or `null`¶

Return: `null`¶

Return: `null`¶

Return: A `PageData` object¶

Return: list of `Hardware` Objects¶

Return: a `PageData` object¶

Return: a `Revision` object¶

Return: a `CredentialConfig` object¶

Return: the updated `CredentialConfig` object¶

Return: A `PageData` object containing a collection of `CredentialSet` objects¶

Return: an `ExecutionData` object.¶

Return: the `JobData` object with `jobId` property populated.¶

Return: `true` if the Job was deleted successfully, `false` otherwise¶

Return: a `JobData` object.¶

Return: a `JobPageData` object containing search results¶

Return: an array of `ToolRunDetails` objects or `null`¶

Return: the `RuleSet` object or `null`¶

Return: an array of `PolicyInfo` objects¶

Return: a `Policy` object or `null`¶

Return: an array of `Violation` objects¶