Skip to content

Advanced Ktranslate Configuration

Jump to bottom
Marc Netterfield edited this page Feb 26, 2026 · 2 revisions

Advanced Ktranslate Configuration

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

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.

# Configuration of every device monitored by this container
devices:
  # 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 Traps
trap:
  listen: 0.0.0.0:1620
  community: public
  version: ""
  transport: ""
  v3_config: null
  trap_only: false
  drop_undefined: false
  # Configuration for the SNMP discovery job
discovery:
  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: true
  global:
  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

Devices section

Key name Required Description
device_name Yes Name of the device. This is the unique identifier for the device.
device_ip Yes Target IP of the device.
snmp_comm Yes (Required for SNMPv1/2c) SNMPv1/2c community string to use.
use_snmp_v1 Yes (Required for SNMPv1)
snmp_v3 Yes (Required for SNMPv3) SNMP v3 config
debug Indicates whether to enable debug level logging during SNMP polling. By default, it's set to false.
port Port to send SNMP queries to. By default, it's set to port 161.
oid Yes (Required for SNMP polling) The discovered systemObjectID for the device. This is used to match the device to a known SNMP profile and set the provider attribute. If no match is found, this sets the provider as a kentik-default device.
description The discovered sysDescr of the device. This field is informational.
last_checked Timestamp when this device was last discovered by the ktranslate Docker image. This field is informational.
mib_profile Yes (Required for SNMP polling) SNMP Profile file that was associated with this device during the discovery run based on its sysOID. If this starts with a bang (!) token, it will override the automatic matching from the sysOID and use a manual override. Ex: "!cisco-asa.yml" (quotes are required).
provider Yes (Required for New Relic) Value used during entity synthesis for New Relic. This is automatically created based on the matched mib_profile and must match one of the rules in the entity-definitions repository in order for an entity to be created. If you are manually adding devices, you will need to take caution to make sure this value is valid.
poll_time_sec Indicates the SNMP polling frequency in seconds. This setting is used to override the global.poll_time_sec attribute.
retries Indicates the number of attempts to retry polling SNMP OIDs. This setting is used to override the global.retries attribute.
timeout_ms Indicates the SNMP polling timeout in milliseconds. This setting is used to override the global.timeout_ms attribute.
user_tags key:value pair attributes to give more context to the device. Tags at this level will be appended to any tags applied in the global.user_tags attribute.
discovered_mibs List of MIBs pulled from matched mib_profile that this device can respond to. This field is informational.
engine_id The unique engine ID discovered for this device's SNMP agent. Generally found during SNMP v3 discovery. This field is informational.
match_attributes attribute:regex pairs to add metrics to allowlist. Pairs at this level will be appended to any pairs applied in the global.match_attributes attribute. Uses the RE2 syntax and has a default OR operator. Prefix key with ! to force to AND operators.
monitor_admin_shut Indicates whether to monitor interfaces in Administratively Shutdown status. By default, it's set to false.
no_use_bulkwalkall Disables the SNMP GETBULK request action when true. By default, it's set to false.
response_time Indicates whether response time polling is enabled for this device. By default, it's set to false.
ping_only Disables all SNMP polling and enables response time polling for this device when true. This setting will override the global.response_time attribute. By default, it's set to false. You will want to make sure you have included the line provider: kentik_ping for each ping_only device.
ping_interval_sec This setting is used to override the default rate of 1 packet/sec used during ping_only | response_time polling.
flow_only Disables all SNMP polling when true. By default, it's set to false.
purge_after_num Removes device from config file after X scheduled discovery jobs have failed. This setting overrides the global purge_devices_after_num setting. Set this to -1 to keep device forever, or any integer >= 1 to set up a purge threshold. (Default: 0)
ext Yes (Required for API Polling) API Polling config
ext.ext_only Disables all SNMP polling for this device_name config. Default: false.

Trap section

Key name Required Description
listen Yes Listening IP port for receiving SNMP traps. By default it's set to 0.0.0.0:1620 and we use a redirect in your docker run ... command to redirect the more common UDP 162 on the host to UDP 1620 in the container. The redirect is done with this flag -p 162:1620/udp
community SNMPv1/v2c community string for receiving SNMP traps. By default we still process incoming traps even if they do not match this community.
version SNMP version to use. Options are v1, v2c, and v3. By default, it's set to v2c.
transport SNMP transport protocol to use. Options are TCP and UDP. By default, it's set to UDP
v3_config SNMP v3 config to use. Only used if version: v3.
trap_only Setting this to true will prevent the container from attempting any SNMP or ICMP polling, used in cases where you want a container that only listens for incoming traps.
drop_undefined Setting this to true will prevent the container from forwarding any SNMP trap messages that are not explicitly defined in an existing SNMP profile. (Default: false)

Discovery section

Key name Required Description
cidrs Yes Array of target IP ranges in CIDR notation. Be mindful with the size of these ranges to avoid a timeout.
ignore_list Array of IP addresses that you wish to explicitly ignore during all discovery jobs.
debug Indicates whether to enable debug level logging during discovery. By default, it's set to false
ports Yes Array of target ports to scan during SNMP polling.
default_communities Yes (Required for SNMPv1/2c) Array of SNMPv1/v2c community strings to scan during SNMP polling. This array is evaluated in order and discovery accepts the first passing community.
use_snmp_v1 Yes (Required for SNMPv1) Indicates whether to use SNMPv1 during discovery. By default, it's set to false
default_v3 Yes (Required for SNMPv3) Single SNMPv3 configuration to scan during SNMP polling.
other_v3s Yes (Required for SNMPv3) Multiple SNMPv3 configurations to scan during SNMP polling. Use this option OR default_v3, not both
add_devices Yes Indicates whether to add discovered devices to the devices section of the snmp-base.yaml file. By default, it's set to true.
add_mibs Yes Indicates whether to add discovered MIBs to the global.mibs_enabled section of the snmp-base.yaml file. By default, it's set to true.
threads Yes Integer limit of threads to use during discovery. It should be less than the number of cores available to the container. By default it's set to 4.
replace_devices Yes Indicates whether to replace discovered devices if they already exist in the devices section of the snmp-base.yaml file. By default, it's set to true.
no_dedup_engine_id When set to true, disables deduplication of discovered devices if it appears that they are the same device, based on their reported SNMP engine ID. By default, it's set to false
check_all_ips When set to true, forces the discovery job to attempt SNMP connectivity against every target IP address from the cidrs array, without checking for liveliness first via TCP port scan. This setting will slow down discovery jobs, but can help bypass issues where discovery is failing against devices that are not listed in your cidrs array with /32 overrides. By default, it's set to false

Global section

Key name Required Description
poll_time_sec Yes Time in seconds to poll devices. This can be overridden per device using the devices.<deviceName>.poll_time_sec attribute. By default, it's set to 60.
drop_if_outside_poll Indicates whether to drop all values from this cycle if polling takes longer than the value set in poll_time_sec. By default, it's set to false.
mib_profile_dir Directory to find curated MIB profiles. These are pulled into the ktranslate image automatically from Kentik's snmp-profiles repository and can be overridden at Docker runtime by creating a volume mount of your own local directory of profiles.
mibs_db
mibs_enabled Yes Array of all active MIBs the ktranslate Docker image will poll. This list is automatically generated during discovery if the discovery_add_mibs attribute is true. MIBs not listed here will not be polled on any device in the configuration file. You can specify a SNMP table directly in a MIB file using MIB-NAME.tableName syntax. Ex: HOST-RESOURCES-MIB.hrProcessorTable.
timeout_ms Yes Time in milliseconds SNMP queries timeout. This can be overridden per device using the devices.<deviceName>.timeout_ms attribute. By default, it's set to 3000.
retries Yes Number of attempts to retry failed SNMP polls. This can be overridden per device using the devices.<deviceName>.retries attribute. By default, it's set to 0.
user_tags key:value pair attributes to give more context to the device. Tags at this level will be applied to all devices in the configuration file.
match_attributes attribute:regex pairs to add metrics to allowlist. Pairs at this level will matched against all devices in the configuration file. Uses the RE2 syntax and has a default OR operator. Prefix key with ! to force to AND operators.
response_time Indicates whether response time polling is enabled for all devices in the configuration file. By default, it's set to false.
purge_devices_after_num Removes devices from config file after X scheduled discovery jobs have failed. Set this to -1 to keep devices forever, or any integer >= 1 to set up a purge threshold. By default, it's set to 0.
watch_profile_changes Sets up a watcher to reload SNMP threads on changes to profiles in the mib_profile_dir path. By default, it's set to false.

Cloud provider secrets

The network monitoring agent has built-in support for retrieving keys from AWS Secrets Manager, Azure Key Vault, and GCP Secret Manager.

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.

Cloud secrets configuration

AWS Secrets Manager

To use AWS Secrets Manager, you will need to set the following three environmental variables and provide them to Docker at runtime:

Name Description
AWS_ACCESS_KEY_ID Specifies the AWS access key used as part of the credentials to authenticate the user.
AWS_SECRET_ACCESS_KEY Specifies the AWS secret key used as part of the credentials to authenticate the user.
AWS_REGION Specifies the AWS Region to send requests to. 
docker run -d --name ktranslate-$CONTAINER_SERVICE --restart unless-stopped --pull=always -p 162:1620/udp \
-v `pwd`/snmp-base.yaml:/snmp-base.yaml \
-e AWS_ACCESS_KEY_ID=$YOUR_AWS_ACCESS_KEY_ID \
-e AWS_SECRET_ACCESS_KEY=$YOUR_AWS_SECRET_ACCESS_KEY \
-e AWS_REGION=$YOUR_AWS_REGION \
kentik/ktranslate:v2 \
-snmp /snmp-base.yaml \
-metrics=jchf \
-tee_logs=true \
-service_name=$CONTAINER_SERVICE \
-snmp_discovery_on_start=true \
-snmp_discovery_min=180

Azure Key Vault

To use Azure Key Vault, you will need to set the following five environmental variables and provide them to Docker at runtime:

You need to set KT_AZURE_KEY_VAULT_NAME or KT_AZURE_KEY_VAULT_URL, not both. The default is to use KT_AZURE_KEY_VAULT_NAME and the agent will use a common URL pattern: https://$KT_AZURE_KEY_VAULT_NAME.vault.azure.net/

Name Description
KT_AZURE_KEY_VAULT_NAME The vault name where the secret is stored.
KT_AZURE_KEY_VAULT_URL Optional full URL for the API call to target.
AZURE_CLIENT_ID Sometimes called the Application ID, this is the identifier for your service principal used to access the secret.
AZURE_CLIENT_SECRET This is the client secret (password) that is used for the service principal during authentication. Note this ID is for the client secret's value, not the ID of the secret itself.
AZURE_SUBSCRIPTION_ID This is the 32-digit GUID associated with the subscription where your secret is managed.
AZURE_TENANT_ID Sometimes called the Directory ID, this is the identifier for the tenant in Microsoft Entra where your service principle is stored. 
docker run -d --name ktranslate-$CONTAINER_SERVICE --restart unless-stopped --pull=always -p 162:1620/udp \
-v `pwd`/snmp-base.yaml:/snmp-base.yaml \
-e KT_AZURE_KEY_VAULT_NAME=$YOUR_KEY_VAULT_NAME \
#### Optional: Provide the full URL to target
# -e KT_AZURE_KEY_VAULT_URL=$YOUR_KEY_VAULT_URL \
-e AZURE_CLIENT_ID=$YOUR_CLIENT_ID \
-e AZURE_CLIENT_SECRET=$YOUR_CLIENT_SECRET \
-e AZURE_TENANT_ID=$YOUR_TENANT_ID \
-e AZURE_SUBSCRIPTION_ID=$YOUR_SUBSCRIPTION_ID \
kentik/ktranslate:v2 \
-snmp /snmp-base.yaml \
-metrics=jchf \
-tee_logs=true \
-service_name=$CONTAINER_SERVICE \
-snmp_discovery_on_start=true \
-snmp_discovery_min=180

GCP Secret Manager

To use GCP Secret Manager, you will need to set the following volume mount for a credential JSON file along with two environmental variables and provide them to Docker at runtime:

Name Description
Service account key Specifies the local file path for the service account key used to authenticate the user. This file is volume mounted into the Docker container and then referenced in the GOOGLE_APPLICATION_CREDENTIALS environment variable.
GOOGLE_APPLICATION_CREDENTIALS Specifies the file path in the container where you've mapped your service account key file.
GOOGLE_CLOUD_PROJECT Specifies the unique project ID where the secret is stored. 
docker run -d --name ktranslate-$CONTAINER_SERVICE --restart unless-stopped --pull=always -p 162:1620/udp \
-v `pwd`/snmp-base.yaml:/snmp-base.yaml \
-v $YOUR_LOCAL_SERVICE_ACCOUNT_KEY_FILE_PATH:/gcp_snmp_sa_key.json \
-e GOOGLE_APPLICATION_CREDENTIALS='./gcp_snmp_sa_key.json' \
-e GOOGLE_CLOUD_PROJECT=$YOUR_PROJECT_ID \
kentik/ktranslate:v2 \
-snmp /snmp-base.yaml \
-metrics=jchf \
-tee_logs=true \
-service_name=$CONTAINER_SERVICE \
-snmp_discovery_on_start=true \
-snmp_discovery_min=180

SNMPv3 options

SNMPv3 configuration

Key name Required Description
user_name Yes User name for SNMPv3 authentication.
authentication_protocolhttps://grafana.com/docs/grafana-cloud/machine-learning/assistant/privacy-and-security/privacy/ Yes SNMPv3 authentication protocol. The possible values are NoAuth, MD5, or SHA
authentication_passphrase SNMPv3 authentication passphrase
privacy_protocol Yes SNMPv3 privacy protocol. The possible values are NoPriv, DES, AES, AES192, AES256, AES192C, or AES256C
privacy_passphrase SNMPv3 privacy passphrase
context_engine_id SNMPv3 context engine ID
context_name SNMPv3 context name

Examples:

Using secrets from AWS, Azure, of GCP will also require that you provide the proper environment variables and any other authentication information needed for the agent to query the target API.

Plain Text

discovery:
default_v3:
user_name: $YOUR_SNMPV3_USER
authentication_protocol: $YOUR_AUTHENTICATION_PROTOCOL
authentication_passphrase: $YOUR_AUTHENTICATION_PASSPHRASE
privacy_protocol: $YOUR_PRIVACY_PROTOCOL
privacy_passphrase: $YOUR_PRIVACY_PASSPHRASE

AWS Secret

discovery:
default_v3: aws.sm.$YOUR_SECRET_NAME

In AWS, you need to store your secrets in a JSON structure with all the relevant key:value pairs. This is an example:

{
"user_name": "$YOUR_SNMPV3_USER",
"authentication_protocol": "$YOUR_AUTHENTICATION_PROTOCOL",
"authentication_passphrase": "$YOUR_AUTHENTICATION_PASSPHRASE",
"privacy_protocol": "$YOUR_PRIVACY_PROTOCOL",
"privacy_passphrase": "$YOUR_PRIVACY_PASSPHRASE"
}

Azure Secret

discovery:
default_v3: azure.kv.$YOUR_SECRET_NAME

In Azure, you need to store your secrets in a multi-line structure with all the relevant key:value pairs. This is an example:

user_name: $YOUR_SNMPV3_USER
authentication_protocol: $YOUR_AUTHENTICATION_PROTOCOL
authentication_passphrase: $YOUR_AUTHENTICATION_PASSPHRASE
privacy_protocol: $YOUR_PRIVACY_PROTOCOL
privacy_passphrase: $YOUR_PRIVACY_PASSPHRASE

GCP Secret

discovery:
default_v3: gcp.sm.$YOUR_SECRET_NAME

In GCP, you need to store your secrets in a multi-line structure with all the relevant key:value pairs. This is an example:

user_name: $YOUR_SNMPV3_USER
authentication_protocol: $YOUR_AUTHENTICATION_PROTOCOL
authentication_passphrase: $YOUR_AUTHENTICATION_PASSPHRASE
privacy_protocol: $YOUR_PRIVACY_PROTOCOL
privacy_passphrase: $YOUR_PRIVACY_PASSPHRASE

Running discovery with multiple SNMP v3 profiles

To support running discovery jobs with multiple SNMP v3 profiles, you can replace the discovery.default_v3 key with the discovery.other_v3s key, which holds an array of SNMPv3 configurations.

discovery:
other_v3s:
- user_name: $YOUR_USER_NAME_1
authentication_protocol: $YOUR_AUTHENTICATION_PROTOCOL_1
authentication_passphrase: $YOUR_AUTHENTICATION_PASSPHRASE_1
privacy_protocol: $YOUR_PRIVACY_PROTOCOL_1
privacy_passphrase: $YOUR_PRIVACY_PASSPHRASE_1
context_engine_id: ""
context_name: ""
- user_name: $YOUR_USER_NAME_2
authentication_protocol: $YOUR_AUTHENTICATION_PROTOCOL_2
authentication_passphrase: $YOUR_AUTHENTICATION_PASSPHRASE_2
privacy_protocol: $YOUR_PRIVACY_PROTOCOL_1
privacy_passphrase: $YOUR_PRIVACY_PASSPHRASE_2
context_engine_id: ""
context_name: ""

This can also work using a cloud provider secrets manager. An example for AWS:

discovery:
other_v3s:
- aws.sm.$YOUR_SECRET_NAME_1
- aws.sm.$YOUR_SECRET_NAME_2

API polling configurations

You can also use cloud provider secrets in your API authentication configuration.

Arista eAPI

The Arista eAPI integration collects additional BGP and MLAG telemetry that isn't typically available via SNMP polling.

Key name Required Description
eapi_config.username Yes The username to pass to the device to authenticate the eAPI authentication.
eapi_config.password Yes The password to pass to the device to authenticate the eAPI authentication.
eapi_config.transport Specifies the type of connection transport to use. The possible values are https and http. Default: https.
eapi_config.port Yes The TCP port of the endpoint for the eAPI connection.

BGP details are collected from this command: show ip bgp summary vrf all

BGP telemetry metric names:

kentik_eapi_bgp.InMsgQueue
kentik.eapi.bgp.MsgReceived
kentik.eapi.bgp.MsgSent
peer_state
kentik.eapi.bgp.UpDownTimecurrent state
kentik.eapi.bgp.Version

MLAG details are collected from this command: show mlag detail

MLAG metric names::

kentik.eapi.mlag.PortsConfigured
kentik.eapi.mlag.PortsDisabled
kentik.eapi.mlag.PortsActivePartial
kentik.eapi.mlag.PortsInactive
kentik.eapi.mlag.PortsActiveFull
kentik.eapi.mlag.PortsErrdisabled
config_sanity
state
neg_status
peer_address
peer_link
peer_link_status
local_interface
local_intf_status

Meraki Dashboard API

The Meraki Dashboard API integration pulls various metrics related to the health of your Meraki environment. The combination of configuration options allows you to set up different monitoring scenarios for your needs and creates entities in your New Relic account.

Primary configuration options You can use the KENTIK_MERAKI_API_KEY environment variable to pass your API key into the Meraki integration without storing it in plain text on your configuration file.

Key name Required Input Description
meraki_config.api_key Yes (Not required if using the KENTIK_MERAKI_API_KEY environment variable) API Key (string) Meraki Dashboard API key for authentication.
meraki_config.max_http_retry Integer between 1-10 (Default: 2) Optional setting that controls how often a retry is attempted on API requests that return a HTTP 429 error. The interval between retries is 5 seconds.
meraki_config.monitor_devices true / false (Default: false) Monitor the status of every Meraki device in the organization.
meraki_config.monitor_org_changes true / false (Default: false) Monitors the change log for the organization.
meraki_config.monitor_uplinks true / false (Default: true) Monitors the uplink status and performance of every Meraki MX, MG and Z series device in the organization.
meraki_config.monitor_vpn_status true / false (Default: false) Monitors the VPN statuses across the networks in the organization.

Filtering options These options allow you to restrict monitoring to specifically targeted objects in your Meraki environment.

Key name Required Input Description
meraki_config.organizations Regex in RE2 syntax (Default: null) Filters all monitoring to a specific list of organizations.
meraki_config.networks Regex in RE2 syntax (Default: null) Filters all monitoring to a specific list of networks.
meraki_config.product_types Valid types are wireless, appliance, switch, systemsManager, camera, cellularGateway, sensor, and cloudGateway. (Default: null) Adds parameters to the monitor_devices API request to filter on specific types of devices.

These options allow you to further define the data collected from the main configuration options. Various combinations are described in the examples section above.

Key name Required Input Description
meraki_config.preferences.device_status_only true / false (Default: false) Required when using monitor_devices: true to restrict polling to only status information. (This is used to prevent timeout issues.)
meraki_config.preferences.hide_uplink_usage true / false (Default: false) Used in combination with monitor_uplinks to remove performance metrics and only return status information for uplinks.
meraki_config.preferences.show_vpn_peers true / false (Default: false) Used in combination with monitor_vpn_status to add telemetry on VPN peers.
meraki_config.preferences.show_network_attr true / false (Default: false) Used to add telemetry on networks. Required to create Meraki Network entities.

Organization metrics are collected by default under the kentik.meraki.organization.Count metric.

Meraki Network Entities

  • meraki_config.preferences.show_network_attr: true

Network metrics are collected under the kentik.meraki.network.Count metric.

Uplink metrics:

kentik.meraki.uplinks.LatencyMS
kentik.meraki.uplinks.LossPct
kentik.meraki.uplinks.Recv
kentik.meraki.uplinks.Sent
status

  • meraki_config.monitor_uplinks: true && meraki_config.preferences.hide_uplink_usage: true: Uses the Get Organization Uplinks Statuses endpoint to list only the uplink status of every Meraki MX, MG and Z series device in the organization.

  • meraki_config.monitor_vpn_status: true && meraki_config.preferences.show_vpn_peers: false: Uses the Get Organization Appliance VPN Statuses endpoint the show VPN statuses across the networks in the organization.

  • meraki_config.monitor_vpn_status: true && meraki_config.preferences.show_vpn_peers: true: Uses the Get Organization Appliance VPN Statuses endpoint to add information about VPN peers across the networks in the organization.

Minimum configuration example

# This represents the minimal configuration required for a container that only performs Meraki API polling.
# By default we only monitor uplinks. All other items are optional.
---
devices:
  meraki_cloud_controller:
    device_name: meraki_cloud_controller
    device_ip: snmp.meraki.com
    provider: meraki-cloud-controller
    ext:
      ext_only: true
      meraki_config:
        api_key: "$YOUR_API_KEY"
trap: {}
discovery: {}
global:
  poll_time_sec: 300
  timeout_ms: 30000

Full configuration examples

All options required to create the Meraki Organization, Meraki Network, and Meraki Device entities.

devices:
  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
        preferences:
          device_status_only: true
          hide_uplink_usage: false
          show_vpn_peers: true
          show_network_attr: true
trap: {}
discovery: {}
global:
  poll_time_sec: 300
  timeout_ms: 30000

Targeting multiple Meraki Dashboard API keys

devices:
  # Entity 1 - monitor everything this API key has access to
  meraki_all:
    device_name: meraki_all
    device_ip: snmp.meraki.com
    provider: meraki-cloud-controller
      ext:
        ext_only: true
        meraki_config:
          api_key: "$YOUR_API_KEY_1"
          max_http_retry: 8
          monitor_devices: true
          monitor_org_changes: true
          monitor_uplinks: true
          monitor_vpn_status: true
          preferences:
            device_status_only: true
            show_vpn_peers: true
            hide_uplink_usage: false
  # Entity 2 - Monitor these specific organizations under this API key
  meraki_single_org:
    device_name: meraki_single_org
    device_ip: snmp.meraki.com
    provider: meraki-cloud-controller
      ext:
        ext_only: true
        meraki_config:
          api_key: "$YOUR_API_KEY_2"
          monitor_devices: true
          monitor_org_changes: true
          monitor_uplinks: true
          monitor_vpn_status: true
          preferences:
            device_status_only: true
            show_vpn_peers: true
            hide_uplink_usage: false
            organizations:
            - "Org 1 - Prod.*"
            - "Org 2 - Staging"
  # Entity 3 - Monitor specific devices filtered by organization, network, and product types; using the same API key from Entity 2
  meraki_filtered:
    device_name: meraki_filtered
    device_ip: snmp.meraki.com
    provider: meraki-cloud-controller
      ext:
        ext_only: true
        meraki_config:
          api_key: "$YOUR_API_KEY_2"
          monitor_devices: true
          monitor_uplinks: false
          preferences:
            device_status_only: true
          organizations:
            - "Org 3 - Remote Sites"
          networks:
            - "Corp.*99"
            - "Retail.*"
          product_types:
            - wireless
            - appliance
trap: {}
discovery: {}
global:
  poll_time_sec: 300
  timeout_ms: 30000

External config files

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.

Discovery CIDRs

Example:

discovery:
cidrs: "@cidrs.yaml"

The CIDRs file should use a YAML list syntax like this:

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

Devices

Example:

devices:
"@neteng-devices.yaml"

The device files should use the same syntax as the standard devices section of the main config file, omitting the optional fields that are generated during discovery:

devices:
# 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
mib_profile: apc_ups.yml
provider: kentik-ups
poll_time_sec: 300
retries: 1
timeout_ms: 5000
user_tags:
owning_team: dc_ops

The 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.

Default 'OR' with null and empty values

Match when if_Alias begins with Uplink OR when if_interface_name begins with Gig, keep all null and "" values:

devices:
deviceName:
...
match_attributes:
if_Alias: "^Uplink.*"
if_interface_name: "^Gig.*"

'AND', omit null and empty values

Match when if_Alias begins with Uplink AND when if_interface_name begins with Gig, drop all null and "" values:

devices:
deviceName:
...
match_attributes:
if_Alias: "^Uplink.*"
"!if_interface_name": "^Gig.*"

Single match, omit null and empty values

Match when if_Alias begins with Uplink, drop all null and "" values:

devices:
deviceName:
...
match_attributes:
"!if_Alias": "^Uplink.*"

Create a negative lookahead

Golang's regex package does not support negative lookahead patterns (q(?!u)) by default. As a workaround, you can add the DOES_NOT_MATCH token to your attribute map to effectively give you the inverse results of your matching pattern.

For example, to match on every interface that does not include the string Uplink; you can use a configuration like this:

devices:
deviceName:
...
match_attributes:
"!if_Alias": "^Uplink.*"
DOES_NOT_MATCH: true

The 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 (default) 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 to 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.

You will have the following ping metrics:

kentik.ping.AvgRttMs
kentik.ping.MaxRttMs
kentik.ping.MinRttMs
kentik.ping.StdDevRtt
kentik.ping.PacketLossPct

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.

The 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.

Flow data application mapping

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

Flow data input filtering

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.

Argument Name Required Description
$TYPE Yes The type of filter to apply. Possible values are string, int, and addr`.
$FIELD Yes The name of the field to evaluate the match pattern against.
$FUNCTION Yes The type of function to use during evaluation. Possible values are Equal: ==, NotEqual: !=, LessThan: <, GreaterThan: >, Contains: %
$MATCH Yes The value to be used as a match pattern.

Example flow filters

  • Only collect flow data from source addresses in the 10.0.0.0/24 CIDR range
-nf.source sflow --filters addr,src_addr,%,10.10.0.0/24
  • Only collect flow data where the destination port is not equal to 8531 
-nf.source netflow5 --filters int,l4_dst_port,!=,8531
  • Only collect flow data from source addresses in the 10.0.0.0/24 CIDR range AND where the destination port is not equal to 8531 (implicit AND operator)
--filters addr,src_addr,%,10.0.0.0/24 --filters int,l4_dst_port,!=,8531

Automatically reloading custom SNMP profiles

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.

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
└── ...

SNMP Overview

Flow Overview

Advanced Settings

Clone this wiki locally