If you want to explore all the options you can use when configuring the monitoring of your network, see the following sections.
snmp-base.yaml
sample file Here's an example of the various configuration options available in the snmp-base.yaml
file used by the ktranslate
Docker image to poll for SNMP and flow data devices. You can also see a heavily-commented sample in the KTranslate repository on GitHub.
# Configuration of every device monitored by this containerdevices: # Sample of SNMP v2c device ups_snmpv2c__10.10.0.201: device_name: ups_snmpv2c device_ip: 10.10.0.201 snmp_comm: $YOUR_COMMUNITY_STRING oid: .1.3.6.1.4.1.318.1.3.27 description: "APC Web/SNMP Management Card (MB:v4.1.0 PF:v6.2.1 PN:apc_hw05_aos_621.bin AF1:v6.2.1 AN1:apc_hw05_sumx_621.bin MN:AP9537SUM HR:05 SN: ABC123DEF456 MD:05/21/2016) (Embedded PowerNet SNMP Agent SW v2.2 compatible)" last_checked: 2021-11-09T18:14:59.907821489Z mib_profile: apc_ups.yml provider: kentik-ups poll_time_sec: 300 retries: 1 timeout_ms: 5000 user_tags: owning_team: dc_ops discovered_mibs: - PowerNet-MIB_UPS - TCP-MIB - UDP-MIB purge_after_num: 1 # Sample of SNMP v3 device router_snmpv3__10.10.0.202: device_name: router_snmpv3 device_ip: 10.10.0.202 snmp_v3: user_name: $YOUR_USER_NAME authentication_protocol: $YOUR_AUTH_PROTOCOL authentication_passphrase: $YOUR_AUTH_PASSPHRASE privacy_protocol: $YOUR_PRIVACY_PROTOCOL privacy_passphrase: $YOUR_PRIVACY_PASSPHRASE oid: .1.3.6.1.4.1.9.1.544 description: "Cisco IOS Software, 3800 Software (C3845-ADVENTERPRISEK9-M), Version 15.1(3)T4, RELEASE SOFTWARE (fc1)\r\nTechnical Support: http://www.cisco.com/techsupport\r\nCopyright (c) 1986-2012 by Cisco Systems, Inc.\r\nCompiled Thu 24-May-12 04:27 by prod_rel_team" last_checked: 2021-11-09T18:14:59.907821489Z mib_profile: cisco-asr.yml provider: kentik-router user_tags: owning_team: core-networking discovered_mibs: - BGP4-MIB - CISCO-MEMORY-POOL-MIB - CISCO-PROCESS-MIB - IF-MIB - OSPF-MIB engine_id: "80:00:01:01:0a:14:1e:28" match_attributes: if_interface_name: "^Ten.*|^Gig.*" "!if_Alias": "[Uu]plink" # Sample of SNMP v1 device netbotz_snmpv1__10.10.0.203: device_name: netbotz_snmpv1 device_ip: 10.10.0.201 snmp_comm: $YOUR_COMMUNITY_STRING use_snmp_v1: true oid: .1.3.6.1.4.1.5528.100.20.10.2013 description: "Linux netbotz930A7A 2.6.12 #307 Wed Dec 29 15:25:32 EST 2010 ppc" last_checked: 2021-11-09T18:14:59.907821489Z mib_profile: apc-netbotz.yml provider: kentik-netbotz user_tags: owning_team: sys_ops discovered_mibs: - IF-MIB - IP-MIB - TCP-MIB - UDP-MIB no_use_bulkwalkall: true # Sample of "flow only" device flow_only__10.10.0.210: device_name: flow_only device_ip: 10.10.0.210 user_tags: owning_team: net_eng flow_only: true # Sample of "ping only" device ping_only__10.10.0.220: device_name: ping_only device_ip: 10.10.0.220 provider: kentik-ping user_tags: owning_team: load_balancing ping_only: true ping_interval_sec: 5 # Sample of Arista eAPI device arista_eapi_10.10.0.230: device_name: arista_eapi device_ip: 10.10.0.230 snmp_comm: public oid: .1.3.6.1.4.1.30065.1.3011.7020.3735.24.2878.2 description: "Arista Networks EOS version 4.22.9M running on an Arista Networks DCS-7020SR-24C2" last_checked: 2021-11-09T18:14:59.907821489Z mib_profile: arista-switch.yml provider: kentik-switch discovered_mibs: - ARISTA-BGP4V2-MIB - ARISTA-QUEUE-MIB - BGP4-MIB - HOST-RESOURCES-MIB - IF-MIB ext: ext_only: false eapi_config: username: $YOUR_ARISTA_API_USERNAME password: $YOUR_ARISTA_API_PASSWORD transport: https port: 443 # Sample of Meraki Dashboard API device meraki_dashboard_api: device_name: meraki_controller device_ip: snmp.meraki.com provider: meraki-cloud-controller ext: ext_only: true meraki_config: api_key: $YOUR_MERAKI_API_KEY monitor_devices: true monitor_org_changes: true monitor_uplinks: true monitor_vpn_status: true organizations: - "Top Org.*" networks: - "Production" - "Guest" product_types: - appliance preferences: device_status_only: true hide_uplink_usage: false show_vpn_peers: true show_network_attr: true# Configuration for receipt of SNMP Trapstrap: listen: 0.0.0.0:1620 community: public version: "" transport: "" v3_config: null trap_only: false drop_undefined: false# Configuration for the SNMP discovery jobdiscovery: cidrs: - 10.0.0.0/24 - 10.0.0.202/32 ignore_list: - 10.0.0.98 - 10.0.0.99 debug: false ports: - 161 - 1161 default_communities: - $YOUR_COMMUNITY_STRING_1 - $YOUR_COMMUNITY_STRING_2 - $YOUR_COMMUNITY_STRING_3 use_snmp_v1: false default_v3: null add_mibs: true threads: 4 add_devices: true replace_devices: true no_dedup_engine_id: false check_all_ips: trueglobal: poll_time_sec: 60 drop_if_outside_poll: false mib_profile_dir: /etc/ktranslate/profiles mibs_db: /etc/ktranslate/mibs.db mibs_enabled: - ARISTA-BGP4V2-MIB - ARISTA-QUEUE-MIB - BGP4-MIB - CISCO-MEMORY-POOL-MIB - CISCO-PROCESS-MIB - HOST-RESOURCES-MIB - IF-MIB - OSPF-MIB - PowerNet-MIB_UPS timeout_ms: 3000 retries: 0 global_v3: null response_time: false user_tags: environment: production match_attributes: if_Description: ".*WAN.*" purge_devices_after_num: 0
The network monitoring agent has built-in support for retrieving keys from AWS Secrets Manager, Azure Key Vault, and GCP Secret Manager.
Important
SNMPv1 and SNMPv2c do not support the use of cloud secrets as the protocols themselves send their community strings via plain text by default. If you are concerned about the security of your SNMP authentication, please update to use SNMPv3.
Tip
You can also use cloud provider secrets in your API authentication configuration.
To support a wide variety of configuration and automation needs, you can use external files that you volume mount into your Docker container to decouple certain elements of the standard configuration file. You will need to include the mount argument below in your docker run
command, with one argument per external configuration file.
-v `pwd`/fileName.yaml:/fileName.yaml \
The syntax for these files is "@fileName.yaml"
, including the double quotes.
match_attributes
attribute To support filtering of data that does not create value for your observability needs, you can set the global.match_attributes.{}
and/or devices.[].match_attributes.{}
attribute map.
This will provide filtering at the ktranslate
level, before shipping data to New Relic, giving you granular control over monitoring of things like interfaces.
The default behavior of this map is an OR
condition, but you can override this and force an AND
operator by prefixing your key name with !
. This is also useful to return only matched items and omit all null
and ""
(empty) results.
response_time
and ping_only
attributes To support monitoring of devices where performance statistics are not accessible or available, or in simple cases where basic round-trip time (RTT) monitoring is required, you can either set the global.response_time
or devices.[].ping_only
attributes to true
.
This feature uses the go-ping package to send either ICMP or unprivileged UDP packets to devices in order to collect the average, min, max, and stddev round-trip time (RTT). This package also shows packet loss percentage for the endpoint based on sending one packet/sec from ktranslate
to the device IP address, which can be overridden by setting the devices.[].ping_interval_sec
attribute. You can switch from the default use of privileged ICMP packets or UDP by setting the KENTIK_PING_PRIV=false
environment variable during Docker runtime.
Setting the global.response_time
attribute to true
will add RTT monitoring on top of existing SNMP polling. To monitor devices with only the UDP|ICMP packets for RTT and no SNMP polling, use devices.[].ping_only: true
.
In New Relic, you can see the results of this polling by investigating the following metrics:
FROM Metric SELECT average(kentik.ping.AvgRttMs) AS 'Average', max(kentik.ping.MaxRttMs) AS 'Max', min(kentik.ping.MinRttMs) AS 'Min', average(kentik.ping.StdDevRtt) AS 'StdDev', latest(kentik.ping.PacketLossPct) AS 'Packet Loss %'FACET device_name
Tip
You can use the ping_only
attribute in replacement of the flow_only
attribute if you would like to collect RTT metrics from a flow device. If both ping_only
and flow_only
are true
, the device will be treated as a flow_only
device.
flow_only
attribute To support monitoring of devices where you only want to collect flow data, you can set the devices.<deviceName>.flow_only
attribute to true
.
This will generate a Flow Device entity which will only have telemetry in the KFlow
event namespace. Alternatively, collecting flow telemetry from a device that is in your configuration file as an SNMP device will add decoration of the KFlow
data to the pre-existing entity, such as a Router or Firewall.
In New Relic, you can see the results of this polling by investigating the following events:
FROM KFlow SELECT *WHERE instrumentation.name = 'netflow-events'
By default, flow telemetry is mapped to known applications based on evaluation of the layer 4 port in use on a specific flow conversation. If needed, you can override the default mapping by providing a YAML file during Docker runtime to the -application_map
flag. This will allow you to specify application names based on ports you identify.
Example syntax:
applications: - ports: [9092, 9093] name: kafka - ports: [80, 8080] name: http - ports: [443, 8443] name: https
By default, flow data containers will collect and process every flow packet they receive. If needed, you can add an inclusion filter to the -nf.source
flag that will ignore all traffic not matching the filter you provide.
By default, the ktranslate
Docker container must be manually destroyed and rebuilt to incorporate changes to the SNMP profiles in the mib_profile_dir path. This is normal behavior in most deployments as the Docker image pulls in the latest profiles available from the public snmp-profiles repository. In situations where you provide custom profiles, you can use the watch_profile_changes setting to enable the container to automatically refresh the underlying configurations and SNMP profiles for the container.
Important
This is not recursive because of a limitation in the watcher library. So, if a profile changes in a subdirectory, you must also edit a top-level file to trigger the change.
Assuming this directory structure:
.└── /snmp-profiles/ └── profiles/ └── kentik-snmp/ ├── 3com ├── _general ├── a10networks └── ...
You will need to place a new file at the root of the directory and manually change it to trigger this refresh cycle. An easy way to implement this is to simply write a timestamp to a file such as last_updated.txt
when your change is submitted.
.└── /snmp-profiles/ ├── last_updated.txt └── profiles/ └── kentik-snmp/ ├── 3com ├── _general ├── a10networks └── ...