cisco.radkit.snmp module – Perform SNMP operations via RADKit

Note

This module is part of the cisco.radkit collection (version 2.0.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install git+https://wwwin-github.cisco.com/scdozier/cisco.radkit-ansible.git. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: cisco.radkit.snmp.

New in cisco.radkit 0.5.0

Synopsis

  • Executes SNMP GET, WALK, GET_NEXT, and GET_BULK operations through RADKit infrastructure

  • Supports both device name and host-based device identification

  • Supports multiple OIDs in a single request for efficient bulk operations

  • Provides configurable timeouts, retries, limits, and concurrency settings

  • Returns structured SNMP response data with comprehensive error handling

  • Ideal for network monitoring, device discovery, and configuration management

Requirements

The below requirements are needed on the host that executes this module.

  • radkit

Parameters

Parameter

Comments

action

string

Action to run on SNMP API

get - Get specific OID values

walk - Walk OID tree (GETNEXT for SNMPv1, GETBULK for SNMPv2+)

get_next - Get next OID values after specified OIDs

get_bulk - Get multiple values after each OID (SNMPv2+ only)

Choices:

  • "get" ← (default)

  • "walk"

  • "get_next"

  • "get_bulk"

client_ca_path

string

Alternate path to client ca cert for RADKIT If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_CLIENT_CA_PATH will be used instead.

client_cert_path

string

Alternate path to client cert for RADKIT If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_CLIENT_CERT_PATH will be used instead.

client_key_password_b64

aliases: radkit_client_private_key_password_base64

string / required

Client certificate password in base64 If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_CLIENT_PRIVATE_KEY_PASSWORD_BASE64 will be used instead.

client_key_path

string

Alternate path to client key for RADKIT If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_CLIENT_KEY_PATH will be used instead.

concurrency

integer

Maximum number of queries to fetch at once (walk/get_bulk only)

Default: 100

device_host

string

Hostname or IP address of the device as it appears in the RADKit inventory. Use either device_name or device_host.

device_name

string

Name of device as it shows in RADKit inventory

identity

aliases: radkit_identity

string / required

Identity to authentiate with RADKit (xxxx@cisco.com). If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_IDENTITY will be used instead.

include_errors

boolean

Include error rows in the output

Choices:

  • false ← (default)

  • true

include_mib_info

boolean

Include MIB information (labels, modules, variables) in output

Choices:

  • false ← (default)

  • true

limit

integer

Maximum number of OIDs to look up in one request (get/get_next)

Maximum number of SNMP entries to fetch in one request (walk)

Number of SNMP entries to get after each OID (get_bulk)

oid

any / required

SNMP OID or list of OIDs to query

Can be dot-separated strings like “1.3.6.1.2.1.1.1.0” or tuple of integers

Multiple OIDs can be provided for bulk operations

output_format

string

Format of the output data

simple - Basic OID and value pairs

detailed - Include all available SNMP row information

Choices:

  • "simple" ← (default)

  • "detailed"

request_timeout

float

Timeout for individual SNMP requests in seconds

Default: 10.0

retries

integer

How many times to retry SNMP requests if they timeout

service_serial

aliases: radkit_serial, radkit_service_serial

string / required

Radkit service serial If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_SERVICE_SERIAL will be used instead.

Examples

- name: Simple SNMP Get
  cisco.radkit.snmp:
    device_name: router1
    oid: "1.3.6.1.2.1.1.1.0"
    action: get
  register: snmp_output
  delegate_to: localhost

- name: SNMP Walk with detailed output
  cisco.radkit.snmp:
    device_name: router1
    oid: "1.3.6.1.2.1.1"
    action: walk
    output_format: detailed
    include_mib_info: true
  register: snmp_output
  delegate_to: localhost

- name: Multiple OID Get with error handling
  cisco.radkit.snmp:
    device_host: "192.168.1.1"
    oid:
      - "1.3.6.1.2.1.1.1.0"
      - "1.3.6.1.2.1.1.2.0"
      - "1.3.6.1.2.1.1.3.0"
    action: get
    include_errors: true
    retries: 3
    request_timeout: 15
  register: snmp_output
  delegate_to: localhost

- name: SNMP Get Next
  cisco.radkit.snmp:
    device_name: switch1
    oid: "1.3.6.1.2.1.2.2.1.1"
    action: get_next
    limit: 10
  register: snmp_output
  delegate_to: localhost

- name: SNMP Get Bulk (SNMPv2+ only)
  cisco.radkit.snmp:
    device_name: router1
    oid: "1.3.6.1.2.1.2.2.1"
    action: get_bulk
    limit: 20
    concurrency: 50
    request_timeout: 30
  register: snmp_output
  delegate_to: localhost

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

data

list / elements=dictionary

SNMP Response data containing OID values and metadata

Returned: success

device_name

string

Name of the device that responded

Returned: success

Sample: "router1"

error_code

integer

SNMP error code if is_error is true (only in detailed format)

Returned: when output_format is detailed and is_error is true

Sample: 0

error_str

string

SNMP error string if is_error is true (only in detailed format)

Returned: when output_format is detailed and is_error is true

Sample: "noSuchName"

is_error

boolean

Whether this row contains an error (only in detailed format)

Returned: when output_format is detailed

Sample: false

label

string

MIB-resolved object ID (only when include_mib_info is true)

Returned: when include_mib_info is true

Sample: "iso.org.dod.internet.mgmt.mib-2.system.sysDescr"

mib_module

string

MIB module name (only when include_mib_info is true)

Returned: when include_mib_info is true

Sample: "SNMPv2-MIB"

mib_str

string

Full MIB string representation (only when include_mib_info is true)

Returned: when include_mib_info is true

Sample: "SNMPv2-MIB::sysDescr.0"

mib_variable

string

MIB variable name (only when include_mib_info is true)

Returned: when include_mib_info is true

Sample: "sysDescr"

oid

string

The SNMP OID as a dot-separated string

Returned: success

Sample: "1.3.6.1.2.1.1.1.0"

type

string

ASN.1 type of the SNMP value (only in detailed format)

Returned: when output_format is detailed

Sample: "OctetString"

value

any

The SNMP value returned

Returned: success

Sample: "Cisco IOS Software"

value_str

string

String representation of the value (only in detailed format)

Returned: when output_format is detailed

Sample: "Cisco IOS Software"

Authors

  • Scott Dozier (@scdozier)