Set up SNMP data monitoring

You can use our guided install process to install the SNMP monitoring agent, or install the agent manually. This doc covers prerequisites to start this install process and a step-by-step walk through of your install options.

Prerequisites

Before you can start, you'll need to sign up for a New Relic account. If you choose to install the agent manually, you also need:

A New Relic account ID.
A New Relic .

It's recommended to deploy the SNMP monitoring agent as a container for either Docker or Podman. If you need it, you can alternatively install it as a baremetal service in Linux.

If you're using Linux to install the agent as a service, you need:

SSH access to the host
Access to install/remove applications and services
One of these supported operating systems:
x84_64/amd64-based CPUs:
- CentOS 8
- Debian 12 (Bookworm)
- Debian 11 (Bullseye)
- Debian 10 (Buster)
- RedHat Enterprise Linux 9 up to 9.5
- Ubuntu 20.04 (Focal LTS)
- Ubuntu 22.04 (Jammy LTS)
- Ubuntu 23.04 (Lunar)
Important
To receive SNMP Traps, the agent must bind to UDP 162. In a host-based install, the following command will be included during the install process. When executed, KTranslate will be run with elevated privileges.
bash
```
$sudo setcap cap_net_bind_service=+ep /usr/bin/ktranslate
```

There are also prerequisites for your network environment and the network devices themselves.

Supported SNMP versions

Our network monitoring container supports all major versions of SNMP (v1, v2c, and v3), including both Traps and Informs. Additionally, SNMP v3 has support for the following authentication and privacy settings:

Setting	Protocol
Authentication	`NoAuth`
Authentication	`MD5`
Authentication	`SHA`
Authentication	`SHA224`
Authentication	`SHA256`
Authentication	`SHA384`
Authentication	`SHA512`
Privacy	`NoPriv`
Privacy	`DES`
Privacy	`AES`
Privacy	`AES192`
Privacy	`AES256`
Privacy	`AES192C`
Privacy	`AES256C`

Tip

We recommend using read-only community strings/authentication with SNMP.

Set up SNMP data monitoring in New Relic

Go to one.newrelic.com > All capabilities > Add more data
Scroll down until you see Network and click SNMP.
Follow the steps outlined in the guided installation process. You can use Docker, Podman, or Linux.
Add SNMP data
one.newrelic.com > All capabilities > Add more data > Network > SNMP to set up SNMP data monitoring.
Investigate your network performance data in the New Relic UI.

Before reading about installing the SNMP agent manually, consider using our guided install process to avoid errors:

Add SNMP data

On a Linux host with Docker installed, download the ktranslate image by running one of the following:
- Docker Hub:
  bash
```
$docker pull kentik/ktranslate:v2
```
- Quay.io:
  bash
```
$docker pull quay.io/kentik/ktranslate:v2
```
Copy the snmp-base.yaml file to the local $HOME directory of your Docker user, and discard the container by running:
bash
```
$cd ~
$id=$(docker create kentik/ktranslate:v2)
$docker cp $id:/etc/ktranslate/snmp-base.yaml .
$docker rm -v $id
```
Edit the snmp-base.yaml file and define the discovery.cidrs and discovery.default_communities attributes to appropriate values for your network.
Tip
We recommend setting discovery.add_mibs: true to automate the addition of all discovered MIBs into the global.mibs_enabled attribute. Additionally, we recommend setting discovery.check_all_ips: true to avoid discovery issues on devices with tightened security postures.
Start the network monitoring agent to poll target devices and listen for incoming SNMP trap messages. Replace $CONTAINER_SERVICE with a unique name for the container and substitute$YOUR_NR_LICENSE_KEY and $YOUR_NR_ACCOUNT_ID with your values:
bash
```
$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 NEW_RELIC_API_KEY=$YOUR_NR_LICENSE_KEY \
>  kentik/ktranslate:v2 \
>  -snmp /snmp-base.yaml \
>  -nr_account_id=$YOUR_NR_ACCOUNT_ID \
>  -metrics=jchf \
>  -tee_logs=true \
>  -service_name=$CONTAINER_SERVICE \
>  -snmp_discovery_on_start=true \
>  -snmp_discovery_min=180 \
>  nr1.snmp
```
Tip
It isn't necessary to run a dedicated agent for trap collection as all SNMP polling agents will run a passive listener. By default the container will listen on the host's port 162 (UDP); but you can change the published port mapping in the docker run command - -p 162:1620/udp. If you want to set up a dedicated container, you can follow the steps in this section.
Investigate your network performance data in the New Relic UI.

On a host with Podman installed, download the ktranslate image by running the following command:
- Docker Hub:
  bash
```
$podman pull docker.io/kentik/ktranslate:v2
```
Copy the snmp-base.yaml file to the local $HOME directory of your Podman user, and discard the container by running:
bash
```
$cd ~
$id=$(podman create kentik/ktranslate:v2)
$podman cp $id:/etc/ktranslate/snmp-base.yaml .
$podman rm -v $id
```
Edit the snmp-base.yaml file and define the discovery.cidrs and discovery.default_communities attributes to appropriate values for your network.
Tip
We recommend setting discovery.add_mibs: true to automate the addition of all discovered MIBs into the global.mibs_enabled attribute. Additionally, we recommend setting discovery.check_all_ips: true to avoid discovery issues on devices with tightened security postures.
Rootless Podman containers arn't able to bind to ports under 1024. To handle packet redirection for trap messages, you'll need to create an iptables rule that targets packets arriving on UDP port 162:
bash
```
$sudo iptables -t nat -A PREROUTING -p udp --dport 162 -j REDIRECT --to-port 1620
```
Start the network monitoring agent to poll target devices and listen for incoming SNMP trap messages. Replace $CONTAINER_SERVICE with a unique name for the container and substitute$YOUR_NR_LICENSE_KEY and $YOUR_NR_ACCOUNT_ID with your values:
bash
```
$podman run -d --name ktranslate-$CONTAINER_SERVICE \
>  --userns=keep-id --restart unless-stopped --pull=always --net=host \
>  -v `pwd`/snmp-base.yaml:/snmp-base.yaml \
>  -e NEW_RELIC_API_KEY=$YOUR_NR_LICENSE_KEY \
>  kentik/ktranslate:v2 \
>  -snmp /snmp-base.yaml \
>  -nr_account_id=$YOUR_NR_ACCOUNT_ID \
>  -metrics=jchf \
>  -tee_logs=true \
>  -service_name=$CONTAINER_SERVICE \
>  -snmp_discovery_on_start=true \
>  -snmp_discovery_min=180 \
>  nr1.snmp
```
Tip
It isn't necessary to run a dedicated agent for trap collection as all SNMP polling agents will run a passive listener. By default, the container will listen on the host's port 162 (UDP), but you can change the published port mapping in the docker run command - -p 162:1620/udp. If want to set up a dedicated container, you can follow the steps in this section.
Investigate your network performance data in the New Relic UI.

Depending on your package manager, use one of the commands below to install ktranslate

Yum:

bash

$curl -s https://packagecloud.io/install/repositories/kentik/ktranslate/script.rpm.sh | sudo bash && \
>  sudo yum install ktranslate

Apt:

bash

$curl -s https://packagecloud.io/install/repositories/kentik/ktranslate/script.deb.sh | sudo bash && \
>  sudo apt-get install ktranslate

Define the environment variables used by ktranslate:

bash

$sudo tee "/etc/default/ktranslate.env" > /dev/null <<'EOF'
$NR_ACCOUNT_ID=$YOUR_NR_ACCOUNT_ID
$NEW_RELIC_API_KEY=$YOUR_NR_LICENSE_KEY
$KT_FLAGS="-snmp /etc/ktranslate/snmp-base.yaml \
>  -metrics=jchf \
>  -tee_logs=true \
>  -service_name=$CONTAINER_SERVICE \
>  -snmp_discovery_on_start=true \
>  -snmp_discovery_min=180 \
>  nr1.snmp"
$EOF
$
$# ensure /etc/default/ktranslate.env is owned by ktranslate user
$sudo chown ktranslate:ktranslate /etc/default/ktranslate.env
$
$# Ktranslate listens for SNMP Traps on privileged port 162. Allow ktranslate to bind to this port with the following command
$sudo setcap cap_net_bind_service=+ep /usr/bin/ktranslate

If you don't have an existing snmp-base.yaml configuration file, create one with:

bash

$sudo tee "/etc/ktranslate/snmp-base.yaml" > /dev/null <<'EOF'
$devices: {}
$trap:
$  listen: '0.0.0.0:162'
$discovery:
$  cidrs:
$    - x.x.x.x/yy
$  ignore_list: []
$  debug: false
$  ports:
$    - 161
$  default_communities:
$    - public
$  default_v3: null
$  add_devices: true
$  add_mibs: true
$  threads: 4
$  replace_devices: true
$  check_all_ips: true
$  use_snmp_v1: false
$global:
$  poll_time_sec: 300
$  mib_profile_dir: /etc/ktranslate/profiles
$  mibs_enabled:
$    - IF-MIB
$  timeout_ms: 3000
$  retries: 0
$EOF
$
$# ensure /etc/ktranslate/snmp-base.yaml is owned by ktranslate user
$sudo chown ktranslate:ktranslate /etc/ktranslate/snmp-base.yaml

Edit the snmp-base.yaml file and define the discovery.cidrs and discovery.default_communities attributes to appropriate values for your network.
Tip
We recommend to set discovery.add_mibs: true to automate the addition of all discovered MIBs into the global.mibs_enabled attribute. Additionally, it is recommended to set discovery.check_all_ips: true to avoid discovery issues on devices with tightened security postures.
Restart the ktranslate service to apply your changes to the snmp-base.yaml file:
bash
```
$sudo systemctl restart ktranslate
```
Investigate your network performance data in the New Relic UI.

Optional installation for SNMP Traps

In some circumstances, it's beneficial to isolate the collection of SNMP trap messages into a dedicated container. This is helpful to control scale in large environments as well as creating a distributed monitoring footprint with lower risk of full outages if a container fails. This process is not supported with the Linux service installation.

Note: You cannot monitor both v2c and v3 traps with the same container. If you want to monitor both trap versions, you'll need to launch a secondary dedicated container and configure your trap messages to be sent on a non-default port. For example, if you have v2c traps already set up on port 162:

Configure your v3 traps to be sent over another port such as 163.
Change the Docker container's arguments slightly, from -p 162:1620/udp to -p $src:1620/udp where $src is the port your v3 traps are arriving on.

On a Linux host with Docker installed, create the configuration file you'll use to run the container:
bash
```
$tee "./traps-base.yaml" > /dev/null <<'EOF'
$devices: {}
$trap:
$  listen: '0.0.0.0:1620'
$discovery: {}
$global:
$  poll_time_sec: 300
$  timeout_ms: 30000
$EOF
```
By default the container will use the source IP address as device names in New Relic. You can control this by mapping devices manually in your configuration file:
```
devices:
  # This key and the corresponding 'device_name'
  # need to be unique for each device
  trap_device1:
    device_name: trap_device1
    device_ip: x.x.x.x/yy
    provider: kentik-trap-device
trap:
  listen: '0.0.0.0:1620'
discovery: {}
global:
  poll_time_sec: 300
  timeout_ms: 30000
```
Tip
You can also control device names by providing a -dns container argument at runtime. This will allow the container to run a lookup on the source IP address and try name resolution.

Start the network monitoring agent to listen for incoming SNMP trap messages. Replace $CONTAINER_SERVICE with a unique name for the container and substitute$YOUR_NR_LICENSE_KEY and $YOUR_NR_ACCOUNT_ID with your values:

bash

$docker run -d --name ktranslate-$CONTAINER_SERVICE -\
>  -restart unless-stopped --pull=always -p 162:1620/udp \
>  -v `pwd`/traps-base.yaml:/snmp-base.yaml \
>  -e NEW_RELIC_API_KEY=$YOUR_NR_LICENSE_KEY \
>  kentik/ktranslate:v2 \
>  -snmp /snmp-base.yaml \
>  -nr_account_id=$YOUR_NR_ACCOUNT_ID \
>  -metrics=jchf \
>  -tee_logs=true \
>  -service_name=$CONTAINER_SERVICE \
>  nr1.snmp

This will start a container that will listen for SNMP trap messages on port 162/udp.

Investigate your results in New Relic by querying the KSnmpTrap event type:
```
FROM KSnmpTrap SELECT *
```
Tip
It's important to remember that SNMP trap messages are events generated by the source device. If you aren't seeing messages in New Relic, ensure your devices have actually created messages. Vendor documentation on sending sample messages varies, but you can use snmptrap on your Docker host to send a test message like this:
bash
```
$snmptrap -v 2c -c public localhost '' 1.3.6.1.4.1.8072.2.3.0.1 1.3.6.1.4.1.8072.2.3.2.1 i 123456
```

On a Linux host with Docker installed, create the configuration file you'll use to run the container:

bash

$tee "./traps-base.yaml" > /dev/null <<'EOF'
$devices: {}
$trap:
$  listen: '0.0.0.0:1620'
$discovery: {}
$global:
$  poll_time_sec: 300
$  timeout_ms: 30000
$EOF

By default the container will use the source IP address as device names in New Relic. You can control this by mapping devices manually in your configuration file:

devices:
  # This key and the corresponding 'device_name'
  # need to be unique for each device
  trap_device1:
    device_name: trap_device1
    device_ip: x.x.x.x/yy
    provider: kentik-trap-device
trap:
  listen: '0.0.0.0:1620'
discovery: {}
global:
  poll_time_sec: 300
  timeout_ms: 30000

Tip

You can also control device names by providing a -dns container argument at runtime. This will allow the container to run a lookup on the source IP address and try name resolution.

Rootless Podman containers are not able to bind to ports under 1024. To handle packet redirection for trap messages, you will need to create an iptables rule that targets packets arriving on UDP port 162:
bash
```
$sudo iptables -t nat -A PREROUTING -p udp --dport 162 -j REDIRECT --to-port 1620
```

bash

$podman run -d --name ktranslate-$CONTAINER_SERVICE \
>  --userns=keep-id --restart unless-stopped --pull=always --net=host \
>  -v `pwd`/traps-base.yaml:/snmp-base.yaml \
>  -e NEW_RELIC_API_KEY=$YOUR_NR_LICENSE_KEY \
>  kentik/ktranslate:v2 \
>  -snmp /snmp-base.yaml \
>  -nr_account_id=$YOUR_NR_ACCOUNT_ID \
>  -metrics=jchf \
>  -tee_logs=true \
>  -service_name=$CONTAINER_SERVICE \
>  nr1.snmp

Investigate your results in New Relic by querying the KSnmpTrap event type:
```
FROM KSnmpTrap SELECT *
```
Tip
It's important to remember that SNMP trap messages are events generated by the source device. If you aren't seeing messages in New Relic, ensure your devices have actually created messages. Vendor documentation on sending sample messages varies, but you can use snmptrap on your Docker host to send a test message like this:
bash
```
$snmptrap -v 2c -c public localhost '' 1.3.6.1.4.1.8072.2.3.0.1 1.3.6.1.4.1.8072.2.3.2.1 i 123456
```

What's next

You can set up more agents to complement your SNMP data:

To get better visibility into how your network is used, set up network flow data monitoring.
To get insights into system messages from your devices, setup network syslog collection.

Prerequisites

Docker installation prerequisites

Podman installation prerequisites

Baremetal Linux service installation prerequisites

Important

SNMP devices prerequisites

Network security prerequisites

Supported SNMP versions

SNMP v3 options

Tip

Set up SNMP data monitoring in New Relic

Guided install setup

Manual container setup

Tip

Tip

Tip

Tip

Tip

Optional installation for SNMP Traps

Manual container setup for SNMP traps

Tip

Tip

Tip

Tip

What's next

Did this doc help with your installation?

Set up SNMP data monitoring

Prerequisites .css-21sua1{background:none;border:none;width:0;padding:0;}

Podman installation prerequisites

Baremetal Linux service installation prerequisites

SNMP devices prerequisites

Network security prerequisites

Supported SNMP versions

SNMP v3 options

Set up SNMP data monitoring in New Relic

Guided install setup

Manual container setup

Optional installation for SNMP Traps

Manual container setup for SNMP traps

What's next

Did this doc help with your installation?

Prerequisites