Kentik NMS Agent

The following topics cover the use of Kentik's Universal agent for our Network Monitoring System (Kentik NMS):

• About the NMS Agent
• NMS Agent Requirements
• NMS Download and Install
• NMS Authentication
• NMS Agent Configuration
• Custom Device Profiles
• NMS Custom Metrics

Note: The following articles provide information about other aspects of Kentik's Network Monitoring System:
- NMS Overview
- NMS Setup
- NMS Dashboard
- Metrics Explorer
- NMS Devices
- NMS Interfaces
- Query Assistant

Kentik's Universal agent is a collector that supports Kentik's Network Monitoring System by collecting data from monitored devices, using protocols such as Simple Network Management Protocol (SNMP) and Streaming Telemetry, and delivering it to the Kentik platform.

Notes:
- Kentik's Universal agent is currently used only for NMS, but will eventually replace all Kentik Agents.
- For details on using Streaming Telemetry for Kentik NMS, see NMS via Streaming Telemetry.

Requirements for Kentik's Universal agent are covered in the topics below.

Hardware requirements vary depending on the expected metrics per second (MPS), which in turn vary depending on the factors including the polling interval and the number of interfaces on the device (two interfaces like an AP vs. 500 interfaces like a chassis). Based on our experience with pilot customers, an MPS range of 27 to 41 per device, averaging around 30, can be expected at a typical polling interval of one minute.

Based on the above, we currently recommend a conservative hardware allocation of one core and 4 gigs of RAM for every 7,500 MPS. We will update this guideline when we have further information from testing at scale. To fully optimize your hardware footprint, we suggest testing in your specific environment.

Repository access depends on whether you elect to deploy a Docker image or a Linux service:

• Docker: You’ll need access to Docker Hub to download the image from kentik/kagent:latest.
• Linux service: If you elect to deploy as a Linux service, no additional network access is required. The setup process uses cURL, so the host will need cURL installed.

The deployed instances will also need to be able to initiate traffic to the following:

• grpc.api.kentik.com (or kentik.eu for Europe) using TLS on TCP 443
• Your monitored network devices using SNMP on UDP 161
• Your monitored network devices using ICMP (Echo)

The Universal agent can be deployed via Docker (or compatible container runtime) or on any systemd-based Linux distribution. We don’t currently publish a deb/rpm package for Universal agent.

Download and installation of the Universal agent for NMS is handled in the Kentik portal (with an assist from Terminal). The process is initiated from one of the following locations:

• NMS Devices page (Network Monitoring System » Devices): Click the Add Devices button in the top right, which opens the Add NMS Devices dialog, where you can choose between full and ping-only monitoring. Choose Full monitoring to go to the NMS Setup Wizard, where you can either select an existing agent from the Select an Agent list or deploy a new agent using the commands provided on the Docker and Linux tabs.
  Note: This method is recommended when the agent will be used only for NMS, because the NMS capability will be configured automatically.
• Universal agent page (Settings » Universal agent): Click the Deploy Agent button at the top right, which opens the Deploy the Universal Agent dialog, where you can either authorize an existing agent from the Select an Agent list or deploy a new agent using the commands provided on the Docker and Linux tabs.
  Note: This method is recommended when deploying and managing multiple Universal agents with a variety of capabilities that aren't exclusively NMS.

The Universal agent uses the same authentication as for other Kentik agents, including kproxy. Authentication uses two custom headers sent by HTTP over TLS:

• X-CH-Auth-Email: The email address associated with a Kentik user, which is found at the top of the User menu at the right of the main portal navbar.
• X-CH-Auth-API-Token: The API token associated with a Kentik user, which is found at the bottom of the User Information pane of the portal's User Profile page (access via User menu).

When you first install an agent, it starts up without a token and announces itself to the Kentik platform in a pending-authorization state. Agents in this state can be viewed and authorized by an admin-level user from the Universal agent page (see NMS Download and Install).

When an admin user approves a new agent, it is provided with an email and token that it stores in /opt/kentik/components/kagent/current/conf/instance-auth.yaml and uses for all future communications with the Kentik platform.

Kentik's Universal agent is configured upon deployment to discover devices within a given IP range for Kentik to monitor. The configuration takes place as part of working through the NMS Setup Wizard. After discovery is complete you can choose which of the found devices to monitor (see NMS Discovery).

Note: NMS data collection via Streaming Telemetry is set up after setting up monitoring via SNMP. For details see NMS via Streaming Telemetry.

When your organization deploys a new agent you may wish to migrate some or all devices from an existing agent to the new one. To do so, no action is required for the old agent. Instead, perform the following steps:

1. Deploy the new agent.
2. Run a regular discovery (see NMS Discoveries Page) of the target IP range with the new agent.
3. In the resulting list, check the checkbox of each discovered device that you'd like to monitor with the new agent.
4. Click the Add Devices button to migrate the selected devices to the new agent.

Kentik maintains and uses a set of device profiles that allow us to normalize metrics and metadata from a wide variety of common device vendors and models. This same profile mechanism can also be used to customize profiles for customer-specific situations, which typically fall into one of the following categories:

• If any of your devices aren't currently supported.
• If a device is supported but you require specific metrics that aren't part of the set of metrics commonly captured from that make/model.
  Note: For a detailed walkthrough of configuration for this use case, see our blog post How to Configure Kentik NMS to Collect Custom SNMP Metrics.

Custom profiles are based on the output of a common Linux utility called snmpwalk. We currently support two approaches to getting the snmpwalk information we need to generate a custom profile:

• Remote SNMP walk (recommended): Allow Kentik to perform remote SNMP walks, then request one for a specific device. See Remote SNMP Walk.
• Manual SNMP walk: Run an SNMP walk yourself on the device, then pass us the information. See Manual SNMP Walk.
  Note: Use this approach only if your organization would prefer not to grant Kentik permission to perform remote SNMP walks.

To enable a custom device profile:

1. Enable remote SNMP walks: On the NMS Devices page, choose Remote SNMP Walks from the Actions menu (see NMS Devices Actions), which will open a dialog in which you can grant us permission to perform snmpwalk operations remotely.
   Note: Your organization needs to grant this permission only once. To remove the permission, open the dialog and switch it off.
2. Request a custom profile: Contact Customer Support to request a custom profile for a specific device. Kentik will run snmpwalk against the device (which must be SNMP-enabled).

If your organization would prefer not to grant Kentik permission to perform remote SNMP walks, you can run snmpwalk internally against any device for which you'd like a custom profile (the device must be SNMP-enabled). You can then provide the output file to your Kentik Customer Support team so we can use it to create a custom profile for the device.

The syntax to run snmpwalk depends on the SNMP version enabled on the device:

• SNMP v1 or v2c:
  snmpwalk --hexOutputLength=0 -ObentUx -v2c -c community X.X.X.X.1 > device-model.walk
• SNMP v3:
  snmpwalk --hexOutputLength=0 -ObentUx -v3 -l authPriv -u username -a SHA -A passphrase -x AES -X passphrase X.X.X.X.1 > device-model.walk

The above commands include the following arguments:

• -v: The specific SNMP version (e.g. 1, 2c, or 3).
• -c (versions 1 and 2c only): The SNMP community configured on the device.
• X.X.X.X: The IP address of the device you are polling (replace with the actual IP).
• -A (v3 only): The authentication protocol passphrase.
• -X (v3 only): The privacy protocol passphrase.
• .1: Following the IP address with ".1" tells snmpwalk to poll all available MIBs on the device (walk the full tree).
  Note: If the device in question carries a full internet routing table, each prefix will show up in multiple MIB trees, in which case you may instead need to walk selected trees and then combine the output. For more information, contact Customer Support.
• device-model.walk: The name of the file to which the output from snmpwalk will be saved. Specify "device" as the vendor and "model" as the model of the device on which snmpwalk was run. For example, if the device is a Cisco ASR9001 then name the file “cisco-asr-9001.walk.”

Kentik NMS enables you to include arbitrary custom metrics in the data that will appear in the portal's Metrics Explorer module. The metrics are submitted via HTTP using a request whose body is made up of data in the InfluxDB Line Protocol, which is the format used by Kentik's Universal agent. While client libraries are available for a wide variety of languages (see https://docs.influxdata.com/influxdb/cloud/api-guide/client-libraries/), it’s also easy to output this format with basic string handling (but be careful about string quoting if you need to handle arbitrary data in string tags).

The URL to which custom metrics may be directed varies depending on the Kentik cluster associated with your account:

• Kentik US cluster: https://grpc.api.kentik.com/kmetrics/v202207/metrics
• Kentik EU cluster: https://grpc.api.kentik.eu/kmetrics/v202207/metrics

Authentication uses the two custom headers described in NMS Authentication.

Notes:
- A User-Agent header is not required, but using it for something descriptive will help with troubleshooting.
- Tags or fields sent with a custom measurement will not age out of Metrics Explorer; they will stay listed indefinitely. In the future we may add ways to tidy obsolete tags and fields as well as to attach metadata such as display names and units.