Migrate from Kproxy to Universal Agent

This article covers how to migrate from Kentik’s legacy kproxy agent to Universal Agent for collecting NetFlow & SNMP telemetry from your network infrastructure devices.

Overview

Still using Kentik’s kproxy standalone software agent? You’ll want to deploy Kentik’s Universal Agent (UA) and take advantage of its Flow Proxy and SNMP/ST capabilities as summarized in this migration checklist:

• Deploy UA and enable the Flow Proxy and/or SNMP/ST capabilities.

• Update your devices and access lists with UA's IP address.

• Configure devices in Kentik for SNMP flow enrichment or full monitoring.

• Decommission the legacy kproxy agent.

Did You Know?: Flow enrichment is included when the device has a FlowPak license. Full monitoring requires a Kentik NMS DevicePak license, and includes many more features including deeper metric visibility, health monitoring, syslog, traps, and SSH access for configs, scrapes and ad-hoc investigation with AI Advisor.

Why Migrate?

Kentik’s Universal Agent (UA) provides a centralized framework for ingesting network telemetry. Consolidating telemetry collection into the UA architecture offers several operational benefits:

• Future-Ready Innovation: The UA is the designated agent platform for all future Kentik feature investments. New capabilities, such as advanced NetBox integrations for infrastructure correlation, are developed exclusively for the UA framework.

• Resource Efficiency: The UA serves as a high-performance source for both Flow data and SNMP metadata. This centralized approach optimizes the processing load on network infrastructure by coordinating telemetry requests through a single, efficient framework.

• Architectural Consolidation: The UA replaces disparate installation procedures and security audit surfaces with a single, managed extension of the Kentik SaaS platform.

Prerequisites

Verify the following environment requirements before beginning the configuration:

• Host Environment: A physical or virtual host running a supported Linux distribution or an environment with Docker container support.

• Agent Registration: The Kentik UA is installed and registered within the Kentik portal.

• Access Control: Administrator permissions for the Kentik portal and appropriate network access (UDP/SNMP) between the host and managed network devices.

Migration Scenarios

Select the configuration path that matches your observability needs:

Scenario 1: Flow Collection Only

Use this path if you require NetFlow, sFlow, or IPFIX ingestion without immediate SNMP-based enrichment.

1. Install and register the Universal Agent on your host.

2. In the Kentik portal, navigate to Settings » Universal Agents.

3. Enable the Flow Proxy capability for the agent.

4. Configure the local listening port (default 9995) and map the agent to the appropriate Site and My Network settings.

5. In Settings » Networking Devices, edit the target device(s) to set their SNMP option to Disable SNMP Collection from this device.

Scenario 2: Enriched Flow without Full Monitoring

Use this path for enriched flow collection. SNMP data is used to map traffic data to interface names, descriptions, and speeds but the device will not be monitored by Kentik NMS or have access to related features.

1. Enable the Flow Proxy capability as described in Scenario 1.

2. Enable the SNMP/ST capability on the same agent instance.

3. In Settings » Networking Devices, edit the target device(s) to set their SNMP option to to Agent-based SNMP for Flow Enrichment.

4. Configure your SNMP v2c or v3 credentials and specify the desired polling intervals.

Scenario 3: Enriched Flow and Full Monitoring

Note: This is the Kentik-recommended path for full visibility and requires a DevicePak license. Collected flow traffic data is enriched with interface names, descriptions, and speeds. The device’s performance, health, and operational state are also monitored by NMS.

1. Enable the Flow Proxy capability as described in Scenario 1.

2. Enable the SNMP/ST capability on the same agent instance.

3. In Settings » Networking Devices, edit the target device(s) to set their SNMP option to to Agent-based SNMP for Flow Enrichment.

4. Configure your SNMP v2c or v3 credentials and specify the desired polling intervals.

Transitioning from Legacy kproxy

If you are currently running the standalone kproxy binary or a Docker container, follow these steps to transition to the Universal Agent with minimal data interruption.

Operational Strategy: Warm Failover

• To ensure no telemetry is lost, the Universal Agent should be configured and set to "Up" status before disabling the legacy process.

• Network devices should be updated to point to the UA IP/Port, and once data flow is verified in the portal, the legacy service can be decommissioned.

Linux Binary Transition

If kproxy is running as a systemd service:

# 1. Verify the Universal Agent is 'Up' in the portal
# 2. Stop and disable the legacy kproxy service
sudo systemctl stop kproxy
sudo systemctl disable kproxy

# 3. Confirm the UA is now binding to the telemetry port (e.g., 9995)
sudo ss -lupn | grep :9995

Note: If you changed the default port in Step 2, replace 9995 with your custom port in the above command.

Docker Container Transition

If kproxy is running as a container, follow these validation steps to ensure data continuity and a safe rollback path.

Step 1: Stop the Legacy Container

First, identify and stop the running container without removing it. This allows for an immediate rollback if the new Universal Agent configuration needs adjustment.

# 1. Identify the running kproxy container
docker ps | grep kproxy

# 2. Stop the legacy container
docker stop <container_id_or_name>

Note: Do not remove the container yet. Leave it in a stopped state so you can quickly restore it if needed.

Step 2: Verify UA is Successfully Receiving Flow

Before permanently removing the container, confirm the Universal Agent is actively collecting data:

1. In the Kentik portal, navigate to Settings » Universal Agents and confirm the Flow Proxy capability shows a status of "Up".

2. Navigate to Settings » Networking Devices and confirm that flow data transmission from the relevant devices has resumed. Look for active traffic records from the interfaces previously handled by kproxy.

3. Allow 5–10 minutes of monitoring to ensure flow continuity and rule out transient collection issues.

Note: After deploying the Universal Agent and enabling the Flow Proxy capability, you may notice that the new agent also appears in the portal under Settings » Kproxy Agents. Because the UA's Flow Proxy utilizes the same core engine as the legacy agent, this dual-listing is expected behavior and does not indicate a migration failure.

Step 3: Finalize or Rollback

If verification succeeds — Remove the legacy container

Once you have confirmed the UA is actively collecting flow data, permanently remove the stopped container:

# Remove the legacy container
docker rm <container_id_or_name>

If verification fails — Restore the legacy container

If flow data is not appearing in the portal after 5–10 minutes, you can safely restore the legacy container to resume collection while you troubleshoot:

CRITICAL: You may need to stop the Universal Agent service/container before restarting the legacy container to avoid a port binding conflict (e.g., both agents attempting to bind to UDP 9995).

# Restart the legacy container to restore previous state
docker start <container_id_or_name>

Once the legacy agent is running again, review the Troubleshooting section to diagnose the Universal Agent issue before reattempting the transition.

Configuration Procedures (UI)

Follow these steps in the Kentik portal to configure Flow and SNMP collection via the Universal Agent.

Step 1: Access Agent Configuration for Capability Install

1. Log in to the Kentik portal and navigate to Settings » Universal Agents.

2. Identify the target agent in the list, then click it to open the management panel.

3. Click Install next to the capability you wish to install.

Step 2: Configure Flow Proxy Capability

1. Select Flow Proxy from the capability list.

2. Click the Edit button to configure the following parameters:

   • Host: The local IP address (default 0.0.0.0).

   • Port: The UDP port for incoming telemetry (e.g., 9995).

   • Site: The site associated with this data.

   • My Network: The internal network boundary definition.

3. Click Save.

Step 3: Configure SNMP/ST Capability

1. Navigate to Settings » Networking Devices.

2. Click the device name from the list you wish to configure.

3. In the top right of the device page, select the gear icon.

4. Select the SNMP tab and configure the enrichment settings as described in the menu:

   1. Credentials: Create a new credential or use an existing credential.

   2. Collection Agent: Select the Kentik agent to collect ST data.

   3. Monitoring Template: Choose a template to be applied for SNMP monitoring.

   4. Device SNMP IP: Enter the IP that Kentik should use to connect to your SNMP Device.

   5. Port: Enter a port number for SNMP polling of your device.

5. Click Save.

Troubleshooting

If you encounter issues during or immediately after the migration, consult the table below for common symptoms and their resolutions.