/

English Español 日本語 한국어 Português

Log in Start now

Set up network syslog monitoring

You can use our guided install process to install the syslog 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 .

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 syslog messages, the agent must bind to UDP 514. 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

Important

ktranslate handles syslog in the following formats automatically: RFC3164, RFC5424, and RFC6587. Any messages received outside of these formats will be discarded unless you configure the -syslog.format=NoFormat flag at runtime.

You must configure source devices to send syslog messages to the host running the network monitoring agent. Here's how to configure network syslog export in some devices (this is not an all-inclusive list):

Checkpoint - Security Gateway. You must sign in to the User Center/PartnerMAP checkpoint.
Cisco - ASA
Cisco - IOS
Cisco - NX-OS
F5 - BIG-IP
Fortinet Fortigate
Juniper - Junos
Palo Alto - PAN-OS

Set up network syslog monitoring in New Relic

For most use cases, we recommended our guided install to set up network flow data monitoring. If your set up is more advanced with custom configurations, then we'd recommend installing manually.

Go to one.newrelic.com > All capabilities > Add more data.
Scroll down until you see Network and click Syslog.
Follow the steps outlined in the guided installation process. You can use Docker or Linux.
Add network syslog data
one.newrelic.com > All capabilities > Add more data > Network > Syslog to set up syslog message monitoring.
Investigate your device syslog messages in the New Relic UI, using the following query:
```
"plugin.type":"ktranslate-syslog"
```
Here's a short video (2:56 minutes) showing how to set up network syslog monitoring:

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

Add network syslog 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 add your syslog devices inside the devices dictionary key with the following structure:
```
devices:
  # This key and the corresponding 'device_name'
  # need to be unique for each device
  syslog_device1:
    device_name: syslog_device1
    device_ip: x.x.x.x/yy
    ping_only: true
    # Optional user tags
    user_tags:
      owning_team: net_eng
      environment: production
```
Important
If you're already monitoring SNMP data devices that will also network syslog messages, you'll want to ensure that the value for device_name is identical for both configuration files to ensure the syslog messages are attributed to the right entity in the New Relic UI.
Run ktranslate to listen for network flows with the command:
bash
```
$docker run -d --name ktranslate-$CONTAINER_SERVICE --restart unless-stopped --pull=always -p 514:5143/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 \
>  -dns=local \
>  # Use this field to create a unique value for `tags.container_service` inside of New Relic
>  -service_name=$CONTAINER_SERVICE \
>  nr1.syslog
```
Tip
The default port the container listens for syslog messages on is 514/udp. If your messages are being sent over a different port, you'll need to change the argument -p 514:5143/udp to -p $srcPort:5143/udp.
Investigate your device syslog messages in the New Relic UI, using the following query:
```
"plugin.type":"ktranslate-syslog"
```

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 add your syslog devices inside the devices dictionary key with the following structure:
```
devices:
  # This key and the corresponding 'device_name'
  # need to be unique for each device
  syslog_device1:
    device_name: syslog_device1
    device_ip: x.x.x.x/yy
    ping_only: true
    # Optional user tags
    user_tags:
      owning_team: net_eng
      environment: production
```
Important
If you're already monitoring SNMP data devices that will also send network syslog messages, you'll want to ensure that the value for device_name is identical for both configuration files to ensure the syslog messages are attributed to the right entity in the New Relic UI.
Rootless Podman containers aren't able to bind to ports under 1024. To handle packet redirection for your syslog messages, you'll need to create an iptables rule that targets the port your packets are arriving on UDP ($scrPort) with the command:
bash
```
$sudo iptables -t nat -A PREROUTING -p udp --dport $scrPort -j REDIRECT --to-port 5143
```

Run ktranslate to listen for syslog messages with the command:

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 \
>  -dns=local \
>  -service_name=ktranslate-$CONTAINER_SERVICE \
>  nr1.syslog

Investigate your device syslog messages in the New Relic UI, using the following query:
```
"plugin.type":"ktranslate-syslog"
```

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 \
>  -dns=local \
>  -service_name=$CONTAINER_SERVICE \
>  -syslog.source=0.0.0.0:514 \
>  nr1.syslog"
$EOF
$
$# ensure /etc/default/ktranslate.env is owned by ktranslate user
$sudo chown ktranslate:ktranslate /etc/default/ktranslate.env
$
$# Syslog binds to privileged port 514. Allow ktranslate to bind to this point 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
```
$cd ~
$touch snmp-base.yaml
```

Edit the snmp-base.yaml file, and add your syslog devices inside the devices dictionary key with the following structure:

devices:
  # This key and the corresponding 'device_name'
  # need to be unique for each device
  syslog_device1:
    device_name: syslog_device1
    device_ip: x.x.x.x/yy
    ping_only: true
    # Optional user tags
    user_tags:
      owning_team: net_eng
      environment: production

Restart the ktranslate service to apply your changes to the snmp-base.yaml file:
bash
```
$sudo systemctl restart ktranslate
```
Investigate your device syslog messages in the New Relic UI, using the following query:
```
"plugin.type":"ktranslate-syslog"
```

Did this doc help with your installation?

What's next?

You can set up some additional agents to complement your network syslog data:

To get better visibility into your network device performance, set up SNMP data monitoring.
To get better visibility into how your network is being used, set up network flow data monitoring.