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.
We recommend using a Docker container to deploy the agent for SNMP monitoring. To use it, you need:
- Docker installed on one of the Linux platforms supported by Docker.
- Ability to launch new containers via command line.
If you're using a Podman container to launch the agent, you need:
- Podman installed on one of the Linux platforms supported by Podman
- Ability to launch new containers via command line
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:
- CentOS 8
- Debian 12 (Bookworm)
- Debian 11 (Bullseye)
- Debian 10 (Buster)
- RedHat Enterprise Linux 9
- 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.
sudo setcap cap_net_bind_service=+ep /usr/bin/ktranslate
There are also prerequisites for your network environment and the network devices themselves.
Check the network security prerequisites for SNMP.
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 |
|
Authentication |
|
Authentication |
|
Authentication |
|
Authentication |
|
Authentication |
|
Authentication |
|
Privacy |
|
Privacy |
|
Privacy |
|
Privacy |
|
Privacy |
|
Privacy |
|
Privacy |
|
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.
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:
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
- Docker Hub:
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 $idEdit the
snmp-base.yaml
file and define thediscovery.cidrs
anddiscovery.default_communities
attributes to appropriate values for your network.Tip
We recommend settingdiscovery.add_mibs: true
to automate the addition of all discovered MIBs into theglobal.mibs_enabled
attribute. Additionally, we recommend settingdiscovery.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.snmpTip
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
- Docker Hub:
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 $idEdit the
snmp-base.yaml
file and define thediscovery.cidrs
anddiscovery.default_communities
attributes to appropriate values for your network.Tip
We recommend settingdiscovery.add_mibs: true
to automate the addition of all discovered MIBs into theglobal.mibs_enabled
attribute. Additionally, we recommend settingdiscovery.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 1620Start 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.snmpTip
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/ktranslateIf 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.yamlEdit the
snmp-base.yaml
file and define thediscovery.cidrs
anddiscovery.default_communities
attributes to appropriate values for your network.Tip
We recommend to setdiscovery.add_mibs: true
to automate the addition of all discovered MIBs into theglobal.mibs_enabled
attribute. Additionally, it is recommended to setdiscovery.check_all_ips: true
to avoid discovery issues on devices with tightened security postures.Restart the
ktranslate
service to apply your changes to thesnmp-base.yaml
file:bash$sudo systemctl restart ktranslateInvestigate 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 as163
. - Change the Docker container's arguments slightly, from
-p 162:1620/udp
to-p $src:1620/udp
where$src
is the port yourv3
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$EOFBy 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 devicetrap_device1:device_name: trap_device1device_ip: x.x.x.x/yyprovider: kentik-trap-devicetrap:listen: '0.0.0.0:1620'discovery: {}global:poll_time_sec: 300timeout_ms: 30000Tip
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.snmpThis 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$EOFBy 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 devicetrap_device1:device_name: trap_device1device_ip: x.x.x.x/yyprovider: kentik-trap-devicetrap:listen: '0.0.0.0:1620'discovery: {}global:poll_time_sec: 300timeout_ms: 30000Tip
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 1620Start 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$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.snmpInvestigate 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.