Retrieve Snmp Agent

Retrieve Snmp Agent

API to get a particular agent given an agent ID. The ID is a combination of 4 attributes "ipAddress" , "port", "contextName" and "contextEnginedId"

Request
URI
GET
https://{api_host}/tcsa.host.com/tcsa/api/v1/snmp/agents/{agentId}
COPY
Path Parameters
string
agentId
Required

The id of the agent being requested

Query Parameters
string
snmpIntegration
Optional

The name of the current snmp integration

snmpIntegration example
snmp-integration

Authentication
This operation uses the following authentication methods.
Responses
200

OK Returned configuration of requested snmp agent

Returns SnmpAgentResponse of type(s) application/json
{
    "devType": "Router",
    "collectorNameList": [
        "checking-Direct.Creation"
    ],
    "agentId": "10.106.232.55:161",
    "doNotUseGetBulkRequests": false,
    "snmpVersion": "v2c",
    "ipAddress": "10.106.232.55",
    "v1TableRowPolling": false,
    "pollingPeriod": 0,
    "capabilitiesWithPollingPeriod": [
        {
            "capabilityName": "CISCO-MEMORY-OLD",
            "pollingPeriod": 0
        },
        {
            "capabilityName": "GENERIC-SYSUPTIME",
            "pollingPeriod": 0
        },
        {
            "capabilityName": "GENERIC-INTERFACES",
            "pollingPeriod": 0
        }
    ],
    "useV3ContextEnginedId": false,
    "discoveryStarted": false,
    "doNotUseCapabilityList": [],
    "maxBulkSize": 50,
    "snmpCommunityOrUserV3Name": "{FB4571C1E38F7FEE40E3768BE0277A7365563DD06438D934B63FEF7865490E8EA3E6E47C0FC874926F8DC4D15FA98696}",
    "transportProtocol": "udp",
    "name": "Agent45",
    "snmpPort": 161,
    "snmpTimeout": 3000,
    "onFailTryWith": "v1",
    "snmpNumberOfRetries": 2,
    "snmpV3Constraint": true,
    "useV3ContextName": false
}
string
name
Required

This required attribute will set the device property to this value for all polled RawValues on this agent.

string
agentId
Optional

The id of the agent. The ID is a combination of 4 attributes "ipAddress" , "port", "v3ContextName" and "v3ContextEnginedId". The id is not required while adding/uploading an agent. This is only filled in the response of an API call

string
ipAddress
Required

This contains the IP address of the polled agent which will be used to contact the device.The pair IP address and port must be unique among all defined agents for this collector.

integer
snmpPort
Required

This port will be used in order to contact the SNMP agent on the polled device. Default one is 161.Please note that the pair IP address and port must be unique among all defined agents for this collector.

string
transportProtocol
Required

The protocol to use for data transportation. Default is UDP.

Possible values are : tcp, udp,
integer
snmpTimeout
Required

The timeout, in milliseconds, before giving up while waiting for the agent response. 1000 is a good value that will fit most of the cases.

integer
snmpNumberOfRetries
Required

The number of retries before giving up while contacting the agent. 2 retries, which mean 3 attempts will be made, should be enough.

string
snmpVersion
Required

The SNMP version to use when polling the agent. Most SNMP agents support v2c, which offers better efficiency than v1. Please note that SNMP v2c (or v3) must be used when polling 64 bits counters.

Possible values are : v1, v2c, v3,
string
snmpCommunityOrUserV3Name
Required

The community string or SNMP v3 username, depending on the selected SNMP version. Filling this attribute is mandatory.

string
snmpV3AuthenticationProtocol
Optional

Only used with SNMP v3. It defines the protocol to use for authentication process.

Possible values are : md5, sha, noAuth, null,
string
snmpV3AuthenticationPassword
Optional

Only used with SNMP v3. It defines the authentication password. Leave blank if not using authentication.

string
snmpV3PrivacyProtocol
Optional

Only used with SNMP v3. It defines the protocol to use for privacy.

Possible values are : aes, des, aes192, aes256, noPriv, null,
string
snmpV3PrivacyPassword
Optional

Only used with SNMP v3. It defines the privacy password. SNMP v3 Authentication only is used when this password is not provided.

integer
maxBulkSize
Required

The maximum number of varbind in a snmpGetBulk request issued to this device. This applies only to SNMP v2c and v3 column-based polling. The default value is 50, which covers most cases. However, it may be required to lower this value if the devices SNMP agent times out when receiving oversized request instead of replying with the largest number of varbinds that may fit in the pdu.

string
v3ContextName
Optional

Only used with SNMP v3. It specifies the context name. Leave it empty for default context.

string
v3ContextEngineId
Optional

Only used with SNMP v3. It specifies the engine ID, as a hexadecimal format character string (i.e. : 0102AAAF ). Leave it empty for default engine ID.

boolean
useV3ContextName
Optional

Only used with SNMP v3 Include the context name as part of the raw values variable for this agent.

boolean
useV3ContextEnginedId
Optional

Only used with SNMP v3 Include the context engined ID as part of the raw values variable for this agent.

string
devType
Required

This attribute is required and describes the type of device this agent represents. All polled values from this agent will be tagged with this property.

string
contactPropertyValue
Optional

The SMARTS contact (sysContact) property for a specific snmpAgent. This is polled as soon as the polling group is created.

string
devdescPropertyValue
Optional

devdescPropertyValue

string
locationPropertyValue
Optional

locationPropertyValue

string
modelPropertyValue
Optional

modelPropertyValue

boolean
discoveryStarted
Optional

discoveryStarted

boolean
v1TableRowPolling
Optional

This attribute affects the way SNMP v1 agents are polled. false is the standard failsafe mode: table polling will be column-based, while true enables a more efficient row-based polling model. However, this feature is not correctly supported by all SNMP v1 agents.

integer
lastSysUpTimeValue
Optional

lastSysUpTimeValue

integer
lastSysUpTimePollTimestamp
Optional

lastSysUpTimePollTimestamp

integer
shortestPollingPeriod
Optional

shortestPollingPeriod

string
port
Optional

port

string
onFailTryWith
Required

This options give the opportunity to issue another call when all retries have failed, using either snmpGet (v1) or snmpGetBulk (v2c) requests.

Possible values are : v1, v2c, disabled,
boolean
doNotUseGetBulkRequests
Optional

Use only get and getNext requests on agent.

integer
refreshPropertiesLastRequestTime
Optional

refreshPropertiesLastRequestTime

array of string
doNotUseCapabilityList
Optional

The names of the capabilities not to be used on this agent

array of string
collectorNameList
Optional

The names of the collectors to which this agent can be distributed

integer
pollingPeriod
Optional

The polling period of the polling group that contains this agent

capabilitiesWithPollingPeriod
Optional

The capabilities assigned to the agent along with their polling periods. By default the polling period assigned to each capability is 0

string
discoveryStatus
Optional

The status of the discovery that was performed on the agent

Possible values are : SUCCESS, FAILED, null,
array of string
discoveryMessage
Optional

A list of error messages in case of failure of discovery.


400

BAD REQUEST Error in the request sent

Returns SnmpError of type(s) application/json
{
    "code": "SNMP_COLLECTOR_API_006",
    "reason": "No Snmp collector running, discovery cannot be performed",
    "status": "404 Not Found"
}
string
code
Optional

This code refers to the internal error codes used in the code base.

string
reason
Optional

This specifies the reason for failure.

string
status
Optional

This specifies the HTTP status code error


404

NOT FOUND Requested object not found

Returns SnmpError of type(s) application/json
{
    "code": "SNMP_COLLECTOR_API_006",
    "reason": "No Snmp collector running, discovery cannot be performed",
    "status": "404 Not Found"
}
string
code
Optional

This code refers to the internal error codes used in the code base.

string
reason
Optional

This specifies the reason for failure.

string
status
Optional

This specifies the HTTP status code error


500

INTERNAL SERVER ERROR Error on the server

Returns SnmpError of type(s) application/json
{
    "code": "SNMP_COLLECTOR_API_006",
    "reason": "No Snmp collector running, discovery cannot be performed",
    "status": "404 Not Found"
}
string
code
Optional

This code refers to the internal error codes used in the code base.

string
reason
Optional

This specifies the reason for failure.

string
status
Optional

This specifies the HTTP status code error