Skip to content

Sample SNMP config

Jump to bottom
Ryan Kadri edited this page Jun 20, 2023 · 24 revisions

Overview

This page serves as an example of the various configuration options available in the snmp-base.yaml config file used for ktranslate to poll for SNMP and receive SNMP Traps.

Aggregated "snmp-base.yaml" Example: 
devices:
  deviceOne:
    device_name: router123
    device_ip: 10.10.0.201
    oid: .1.3.6.1.4.1.2636.1.1.1.2.21.0
    snmp_comm: public
    poll_time_sec: 300
    user_tags:
      owning_team: net_eng
      environment: production
trap:
  listen: 127.0.0.1:162
  community: public
  version: ""
  transport: ""
  v3_config:
discovery:
  cidrs:
  - 10.10.0.0/24
  - 10.20.0.0/24
  - 192.168.0.21/32
  debug: false
  ports:
  - 161
  - 1161
  default_communities:
  - public
  default_v3: null
  add_devices: true
  threads: 4
  use_snmp_v1: false
  replace_devices: true
global:
  poll_time_sec: 300
  timeout_ms: 5000
  retries: 0
  mibs_enabled:
  - IF-MIB
  drop_if_outside_poll: false
  mib_profile_dir: profiles

Devices Config Section

Config Item Required? Description
device_name Y Name of the device to report to New relic
device_ip Y IP to send SNMP queries to
port N Port to send SNMP queries to (Default: 161)
provider N Value used during entity synthesis for New Relic
mib_profile N Which SNMP Profile file was associated with this device during discovery based on its sysOID
snmp_comm Y* SNMPv1/2c community string to use. Set this OR snmp_v3 if using SNMPv3
use_snmp_v1 N Boolean indicator that enables SNMPv1 (Default: false)
snmp_v3 N SNMPv3 authentication config
poll_time_sec N Optional override of global polling frequency, in seconds (Default: 60)
timeout_ms N Optional override of global polling timeout, in milliseconds (Default: 5000)
retries N Optional override of global number of retries to attempt (Default: 0)
last_checked N Timestamp that this device was last discovered by ktranslate
oid Y sysOID for this device
description N Human-readable description of this device
discovered_mibs N List of MIBs from our known SNMP Profiles this device can respond to found during discovery by ktranslate
debug N Runs SNMP polling in debug mode (Default: false)
user_tags N Additional key:value pair attributes to decorate all metrics from this device with
match_attributes N attribute:regex pairs to whitelist metrics. Only matching attributes are sent.
monitor_admin_shut N Boolean. If true, monitor shut interfaces also. Defaults to false.
no_use_bulkwalkall N Boolean. If true, do not use BulkWalkAll snmp operation. Set true if the device doesn't support this. (Default: false)
instrumentationName N String. If set, overrides what profile is used in NR. Do not set unless you know what you are doing.
response_time N Boolean. If true, send a ping to measure RTT from the collector to this device.
purge_after_num N Integer. If a device is present in the config file but stops appearing throughout purge_after_num consecutive discovery attempts, remove it from the list of devices. This value will override the purge_devices_after_num global setting. A value of -1 means devices will never be auto-removed. If this value is not provided, devices will not be auto-removed.
"devices" Config Example: 
devices:
  deviceOne:
    device_name: router123
    device_ip: 10.10.0.201
    oid: .1.3.6.1.4.1.2636.1.1.1.2.21.0
    snmp_comm: public
    poll_time_sec: 300
    user_tags:
      owning_team: net_eng
      environment: production
    match_attributes:
      if_Description: "^igb|^eth"

Note you can optionally provide an array of external files with device config information instead of adding them directly to the base file

Optional "devices.yaml" Example:

Config Snippet:

devices: 
  - "@networking-devices.yaml"
  - "@security-devices.yaml"

File Example:

deviceOne:
  device_name: router123
  device_ip: 10.10.0.201
  oid: .1.3.6.1.4.1.2636.1.1.1.2.21.0
  snmp_comm: public
  poll_time_sec: 300
  user_tags:
    owning_team: net_eng
    environment: production

During the discovery process, the value of provider is set based on matching of the known mib_profile and oid. If there is not a good match, the value defaults to kentik-default so we don't create improper entities in the New Relic UI. This value can be manually overriden in the device config block, but care should be taken during subsequent discoveries to ensure replace_devices is set to false so you don't accidentally reset all of your device settings.

Note that setting this value will create an entity in New Relic, but the default metrics and dashboard of that entity still depend on certain telemetry being present. For example, if you set a device to kentik-router, but you don't have a MIB profile setup to collect CPU and Memory utilization telemetry from SNMP; then your associated entity in New Relic will have blank charts.

Currently Supported Values for "provider"

Trap Config Section

Config Item Required? Description
listen Y Listening IP:Port for receiving SNMP Traps
community N SNMP community string for receiving SNMP Traps
version N SNMP version to use: v1, v2c (default) supported today, v3
transport N SNMP transport protocol to use [TCP|UDP] (Default: UDP)
v3_config N SNMP v3 config to use. Only used if version is v3.
"trap" Config Example: 
trap:
  listen: 127.0.0.1:162
  community: public
  version: ""
  transport: ""
"trap" V3 Config Example: 
trap:
  listen: 127.0.0.1:162
  version: v3
  transport: ""
  v3_config: 
    user_name: test
    authentication_protocol: SHA
    authentication_passphrase: Pa33Word
    privacy_protocol: AES
    privacy_passphrase: hunter2
    context_engine_id: ""
    context_name: ""

Discovery Config Section

Config Item Required? Description
cidrs Y Array of target IP ranges (or optional external file) in CIDR notation Can use /32 to force SNMP poll without first testing with ICMP echo
ports Y Array of target ports to scan during SNMP polling
default_communities Y Array of SNMPv1/v2c community strings to scan during SNMP polling; This array is evaluated in order and discovery will accept the first passing community Set this OR default_v3 if using SNMPv3
default_v3 N SNMPv3 config to scan during SNMP polling
other_v3s N List of other SNMPv3 configs to scan during SNMP polling. These are appended to any value in default_v3 and checked in order.
use_snmp_v1 N Boolean indicator for use of SNMPv1 during discovery (Default: false)
add_devices Y Boolean indicator for adding discovered devices to devices segment of config file (Default: true)
add_mibs Y Boolean indicator for adding discovered MIBs to global.mibs_enabled segment of config file (Default: true)
replace_devices Y Boolean indicator for replacing discovered devices if they already exist in the devices segment of config file (Default: true)
debug N Boolean indicator to enable debug level logging during discovery (Default: false)
threads Y Integer limit of threads to use during discovery Should be less than the number of cores available to the container
no_dedup_engine_id N Turn off a feature which removes devices who share a common SNMP Engine ID.
check_all_ips N If true, check connectivity to all ips in the cidr block, even if the port scan thinks that this ip is down.
"discovery" Config Example: 
discovery:
  cidrs: "@cidrs.yaml"
  debug: false
  ports:
  - 161
  default_communities:
  - public
  default_v3: null
  add_devices: true
  threads: 4
  use_snmp_v1: false
  replace_devices: true

Note you can optionally provide an external file with CIDR information instead of adding them directly to the base file

Optional "cidrs.yaml" Example:

Config Snippet:

discovery:
  cidrs: "@cidrs.yaml"

File Example:

- 10.10.0.0/24
- 10.20.0.0/24
- 192.168.0.21/32

SNMPv3 Config Section

Config Item Required? Description
user_name Y User name for SNMPv3 authentication
authentication_protocol Y SNMPv3 authentication protocol [NoAuth|MD5|SHA]
authentication_passphrase N SNMPv3 authentication passphrase
privacy_protocol Y SNMPv3 privacy protocol [NoPriv|DES|AES|AES192|AES256|AES192C|AES256C]
privacy_passphrase N SNMPv3 privacy passphrase
context_engine_id N SNMPv3 Context EngineID
context_name N SNMPv3 Context Name
Optional "SNMPv3" Config Example: 
  default_v3:
    user_name: userNamev3
    authentication_protocol: MD5
    authentication_passphrase: authPassPrivacy
    privacy_protocol: AES256
    privacy_passphrase: passPrivacy
  other_v3s:
  - user_name: test2
    authentication_protocol: MD5
    authentication_passphrase: authPassPrivacy2
    privacy_protocol: AES256
    privacy_passphrase: passPrivacy2
  - user_name: test3
    authentication_protocol: MD5
    authentication_passphrase: authPassPrivacy3
    privacy_protocol: AES256
    privacy_passphrase: passPrivacy3
Ways to pass secrets into "SNMPv3 Configs"
  1. Use an environmental variable:
    authentication_passphrase: ${DEVICE_AUTH_PASSPHRASE}
  1. Use AWS Secrets Manager:
    authentication_passphrase: aws.sm.MyDeviceAuthValue

When using AWS, be sure to set any needed AWS environmental variables needed, for example AWS_REGION=us-east-2 AWS_PROFILE=labs. The prefix aws.sm. will cause the key MyDeviceAuthValue to be retrieved from AWS SM.

Global Config Section

Config Item Required? Description
poll_time_sec Y Poll device metrics on this interval (Default: 300)
timeout_ms Y Timeout queries after this long (Default: 5000)
retries Y Retry failed polls this many times (Default: 0)
mibs_enabled Y Array of all active MIBs ktranslate will poll; polling will only occur if the MIB is valid for a given device
drop_if_outside_poll N If the complete polling of metrics takes longer than poll_time_sec, drop all values from this cycle (Default: false)
mib_profile_dir N Directory to find curated MIB profiles
response_time N Boolean. If true, send a ping to measure RTT from the collector to all devices.
user_tags N Additional key:value pair attributes to decorate all metrics from all devices with.
match_attributes N attribute:regex pairs to whitelist metrics. Only matching attributes are sent.
purge_devices_after_num N Integer. If a device is present in the config file but stops appearing throughout purge_devices_after_num consecutive discovery attempts, remove it from the list of devices. By default, devices will not be auto-removed.
"global" Config Example: 
global:
  poll_time_sec: 300
  timeout_ms: 5000
  retries: 0
  mibs_enabled:
  - IF-MIB
  drop_if_outside_poll: false
  mib_profile_dir: profiles

SNMP Overview

Flow Overview

Clone this wiki locally