SNMP Quickstart

Pre-reqs

Validate you have docker installed and running (docs)

docker version --format '{{.Server.Version}}'

Validate you have a non-root user available in the docker group (docs)

/etc/group -e "docker"

Step 1

Download the ktranslate image from dockerhub:

docker pull kentik/ktranslate:v2

Step 2

Copy the SNMP config file to your local $HOME directory for your docker user and discard the container:

cd .
id=$(docker create kentik/ktranslate:v2)
docker cp $id:/etc/snmp-base.yaml .
docker rm -v $id

Step 3

Edit the SNMP config file (snmp-base.yaml) with your preferred text editor, setting cidrs: and default_communities: to appropriate values for your network

Step 4

Run a discovery on SNMP devices based on the CIDR and Community String values you've configured:

docker run -ti --name ktranslate --rm --net=host \
  -v `pwd`/snmp-base.yaml:/snmp-base.yaml \
  kentik/ktranslate:v2 \
    -snmp /snmp-base.yaml \
    -log_level info \
    -snmp_discovery=true

Towards the end of the discovery process, you should see a log line similar to:

[Info] KTranslate Adding 3 new snmp devices to the config, 0 replaced from 3

The above example indicates discovery found 3 new devices

If nothing is discovered, increase the timeout value timeout_ms: in the config file and re-run discovery.

Consider setting check_all to true as well. This will slow down the discovery process but find otherwise hidden devices.

If still nothing is discovered, set the cidrs: blocks to be only /32 length. This forces the discovery process into a more in depth mode which should work as long as the device is reachable via SNMP.

After successful discovery, devices are listed in the snmp-base.yaml file. By default, only the mib IF-MIB is polled. Add other mibs here as your devices support them.

Step 5

Lastly, start ktranslate to run in background and poll target devices:

Example: Output to JSON

docker run -ti --name ktranslate --rm --net=host \
  -v `pwd`/snmp-base.yaml:/snmp-base.yaml \
  kentik/ktranslate:v2 \
    -snmp=/snmp-base.yaml \
    -log_level=info \
    -format=json 

Example: Output to New Relic sink

This will require you have your New Relic Account ID and Insights Insert Key, replacing $NR_INSIGHTS_INSERT_KEY and $NR_ACCOUNT_ID in this command, respectively

docker run -d --name ktranslate --net=host \
  -e NEW_RELIC_API_KEY=$NR_INSIGHTS_INSERT_KEY  \
  -v `pwd`/snmp-base.yaml:/snmp-base.yaml \
  kentik/ktranslate:v2 \
    -snmp /snmp-base.yaml \
    -compression=gzip \
    -sinks=new_relic \
    -nr_account_id=$NR_ACCOUNT_ID \
    -log_level=info \
    -format=new_relic_metric 

Troubleshooting

Get logs with docker logs ktranslate