Universal Agents

This article covers the Universal Agents page in the Kentik portal.

About the Universal Agent

Kentik’s Universal Agent collects key metrics on the availability, health, and performance of your network infrastructure. After installing the agent on a host machine on your network (see Deploy the Universal Agent), you add features to the agent by installing Agent Capabilities.

Did You Know?: All Kentik agents (see Agents) will gradually be replaced with Agent Capabilities of the Kentik Universal Agent.

Agent Capabilities

General features of a Universal Agent capability:

• Automatically updates itself

• Sends host metrics and capability metrics, usable in Data Explorer and Metrics Explorer

• Agent/capability metrics can be used to create agent alerts

Supported Capabilities:

Notes:

• The DNS OTT Tap capability replaces the standalone kprobe software agent as the method for tapping DNS data, as described in Enabling OTT DNS Collection.

• The Flow Proxy capability replaces the standalone kproxy software agent as the method for forwarding flow telemetry data.

Agent Status

A deployed Universal Agent can be in one of the following states, as indicated in the Status column of the Universal Agents list:

• Up: The agent was last seen by Kentik within 30 minutes.

• Down: The agent was last seen by Kentik over 30 minutes ago.

• Not Authorized: The agent is not yet authorized to connect to Kentik.

Note: Authorization is part of the agent installation process (see Deploy the Universal Agent).

Deploy a Universal Agent

To deploy a new instance of the Universal Agent via Docker or Linux, follow these steps:

1. Go to the Universal Agents Page via Settings » Universal Agents in the Kentik portal’s main nav menu.

2. Click + Deploy Agent to open the dialog.

3. Under Installation, choose Docker or Linux and click the corresponding tab. The necessary command will appear in the text area below the tabs.

4. Click Copy to copy the command from the text area.

5. Open a terminal window on the host machine and paste the command. (To use a web proxy, see Install Agent via Web Proxy).

6. Run the command. The new agent will appear in the Select an Agent list. The Host Name column will vary as follows:

   1. Docker: The agent's Docker container ID.

   2. Linux: The hostname of the Linux system where the agent was installed.

7. Click Authorize to authorize the agent to connect with Kentik. The dialog will refresh with basic information, optional fields, and a Continue button.

   

8. Optionally add Display Name, Description, and Site Name. Click Continue to proceed.

9. Select the capabilities to enable for this agent by clicking the toggle switch next to each capability.

   

10. Click the Finish button to complete the deployment process. Once deployed, the agent will appear on the Universal Agents List.

Tip: If you close the dialog before clicking Authorize, the agent will appear on the Universal Agents List with a “Not Authorized“ status and won't be functional. To resolve this, click Deploy Agent to reopen the dialog and click Authorize.

Install Agent via Web Proxy

Use the https_proxy environment variable to set the proxy's URL:

• Docker: Provide the environment variable as part of the docker run command:

  --env https_proxy=http://address.of.your.proxy

• Linux: Set the environment variable before running the install command:

  export https_proxy=http://address.of.your.proxy

Edit a Universal Agent

To edit a deployed Universal Agent instance, follow these steps:

1. Navigate to the Universal Agents Page via Settings » Universal Agents in the Kentik portal’s main nav menu.

2. Click the edit button (pencil icon) in the agent's row in the list.

3. Update the Name, Description, Closest Network Device, and/or Site.

4. Click Save to save changes and exit or Cancel to exit without saving.

Install a Capability

To install a capability (see Agent Capabilities) on a Universal Agent instance, follow these steps:

1. Go to the Universal Agents Page via Settings » Universal Agents in the Kentik portal’s main nav menu.

2. Click the agent's row in the list to open the Agent Details Drawer.

3. Under Capabilities » Available: Compatible and Supported, click Install for any capabilities you wish to add this Universal Agent instance.

Manage a Capability

To manage an installed capability on a Universal Agent instance, follow these steps:

1. Go to the Universal Agents Page via Settings » Universal Agents in the Kentik portal’s main nav menu.

2. Click the agent's row in the list to open the Agent Details Drawer.

3. Under Capabilities » Installed: Running or Paused on this Agent, click Details.

4. In the Capability Drawer, you can take the following actions:

   1. View the capability’s details like Status, Run State, Command Line Args, and metrics visualizations.

   2. When applicable, click Edit to reveal additional capability settings like command line arguments/values.

      1. Click Save to save changes and exit or Cancel to exit without saving.

   3. Click Back to return to the Agent Details drawer.

   4. Click Disable this Capability to temporarily turn off this capability for this Universal Agent instance.

Configure the DNS OTT Tap Capability

To edit an OTT DNS Tap capability, follow these steps:

1. Go to the Universal Agents Page via Settings » Universal Agents in the Kentik portal’s main nav menu.

2. Click the agent's row in the list to open the Agent Details Drawer.

3. Under Capabilities » Installed: Running or Paused on this Agent, click Details for DNS OTT Tap.

4. Click Edit to reveal the current command line argument/value settings.

5. Make the changes, as follows:

   1. Update an Existing Argument: Select a different Command Line Value from the dropdown.

   2. Add a New Argument: Click Add to add a row, then choose the argument and value (see supported combinations below).

6. Click Save to save changes and exit or Cancel to exit without saving.

Supported argument/value combinations for the DNS OTT Tap capability:

Configure the Flow Proxy Capability

To configure the Flow Proxy capability of the Universal Agent, which receives, processes, and forwards your flow telemetry data to Kentik, follow these steps:

Note: The Flow Proxy capability packages the standard Kentik Proxy (kproxy) binary into a managed component within the Universal Agent framework.

1. Go to the Universal Agents Page via Settings » Universal Agents in the Kentik portal’s main nav menu.

2. Click the agent's row in the list to open the Agent Details Drawer.

3. Under Capabilities » Installed: Running or Paused on this Agent, click Details for Flow Proxy.

4. Click Edit to reveal the current command line argument/value settings.

5. Configure the command-line arguments as necessary (see below table), and click Save.

   1. The Universal Agent downloads the kproxy binary, applies the configuration, and starts the process.

   2. The agent’s Status field on the Universal Agents page updates from 'Pending' to 'Up'.

6. Configure your routers, switches, and other network devices to export flow telemetry to the IP address of the Universal Agent host on the UDP port specified in the Port field (e.g., 9995).

Troubleshooting a Flow Proxy

• Status is Down: If the capability status displays 'Down' with an error, such as exit status 10, it typically indicates a configuration error. Ensure that all required fields are correctly populated.

• No Data in Portal: If the capability status is ‘Up’ but you see no flow data in the Kentik portal, verify the following:

  • Network devices are configured with the correct destination IP and port.

  • There are no firewalls on the agent’s host or in the network path blocking the flow export UDP port.

  • Check the agent logs for connection errors or other warnings.

Uninstall a Capability

To uninstall a capability from a Universal Agent instance, follow these steps:

1. Go to the Universal Agents Page via Settings » Universal Agents in the Kentik portal’s main nav menu.

2. Click the agent's row in the list to open the Agent Details Drawer.

3. Under Capabilities » Installed: Running or Paused on this Agent, click Uninstall for the capability you wish to remove from this Universal Agent instance. Once the capability has been removed, you’re returned to the Agents list.

Tip: You can reinstall a capability on an agent at any time by clicking the capability’s Install button in the Agent Details Drawer.

Universal Agents Page UI

The Universal Agents page, accessible via Settings » Universal Agents in the main nav menu, allows you to manage all the Universal Agents deployed by your organization.

Key UI elements include:

• Auto-refresh/Refresh: Automatically or manually updates the agent list.

• Deploy Agent (Admin-only): Opens the Deploy the Universal Agent dialog for deploying new agents.

• Show/Hide Filters: Toggles the Filters pane (see Universal Agents Filters).

• Search: Restricts the Universal Agents List based on keywords you enter and/or filters you select

  • To clear all entered text, click the X in the Search field.

  • To clear a filter, click the X in a lozenge.

  Note: For text-based searches, keywords are matched against the Name and Capabilities columns only.

• Filters: Provides controls to narrow the agents list (see Universal Agents Filters).

• Universal Agents List: A table displaying your deployed Universal Agents.

Note: Member-level users can view Universal Agents, but only Admin-level users can add, edit, or remove them (see About Users).

Universal Agents Filters

The Filters pane on the left of the Universal Agents List refines the list based on these options:

• Capability: Filters by installed capabilities (see Agent Capabilities).

• Status: Filters by agent status (e.g., “Up”).

• Version: Allows adding and removing filters for specific agent versions via a dropdown list.

• Site: Allows adding and removing filters for specific sites (see About Sites) via a dropdown list.

Notes:

• Add a Version or Site filter by selecting one or more values from the dropdown.

• To remove any filter, click the X in the lozenge in the search field.

Universal Agents List

The Universal Agents list shows all the deployed Universal Agents for your organization. To change the sort order of the list, click a heading to select a column, then click the resulting blue up or down arrow to choose the sorting direction (ascending or descending).

List Columns

The Universal Agents list includes the following columns of information about each deployed Universal Agent:

• Status: Agent's current operational state.

• Name: Agent's assigned name.

• CPU: Percentage of CPU utilized by the agent.

• MEM: Percentage of memory utilized by the agent.

• Public IP: Agent's public IP address.

• Private IP: Agent's private IP address.

• Site: Associated site name.

• Version: Agent's software version.

• Capabilities: Tags indicating agent functionalities.

List Actions

The Universal Agents list includes the following action buttons per row:

• Edit (pencil icon): Modify agent properties (see Edit Agent Drawer).

• Remove (trash icon): Delete the agent instance (requires confirmation).

Agent Details Drawer

Access the Agent Details drawer by clicking an agent's row in the Universal Agents List.

Agent Details UI

The Agent Details drawer includes the following UI elements:

• Close (button): Closes the drawer.

• Name: Displays the agent's name.

• Edit (button): Opens the Edit Agent Drawer.

• Properties (fields): A set of fields with metadata about the agent (see Agent Details Fields).

• Capabilities (pane): Lists the agent's capabilities in collapsible sections by Capability Categories, each with:

  • Install (button): Installs a capability.

  • Details (button): Opens a detailed view of an installed capability (see Capability Drawer).

  • Toggles (switch): Turns a capability ON (blue) or OFF (grey).

• Metrics (pane): Charts showing the agent's CPU and memory utilization for the last hour (all capabilities combined).

• View in Metrics Explorer (button): Opens the view in Metrics Explorer.

Note: When a capability section is collapsed, the total count of capabilities for that section is shown in a blue bubble.

Capability Categories

Capability categories shown in the Agent Details drawer are:

• Installed: Running or Paused on this Agent

• Available: Compatible and Supported

• Available: Compatibility not guaranteed

• Upcoming: Planned future release

Agent Details Fields

Agent properties are listed in the drawer and include the following:

• Status: The agent status (e.g., "Up").

• Host Name: The name of the host where the agent is deployed.

• Version: The Kentik-maintained version number for the agent.

• Public IP: The public IP address of the agent's host machine.

• Private IP: The private IP address of the agent's host machine.

• Site: The site to which the agent is associated, if any.

• Description (only if specified): A description string specified in the agent's settings

• Closest Device: A field with two states:

  • If the Closest Network Device field is already specified in the Edit Agent Drawer, this field shows that value.

  • If the value isn't already specified, this field is an Edit link which opens the Edit Agent Drawer, enabling you to specify the closest device.

• Host OS: The operating system and CPU type of the agent’s host machine.

• Created on: The date-time when the agent was created.

• Last seen on: The date-time when the agent last connected to Kentik.

• Agent ID: The ID number (integer) of the agent.

• Install ID: A unique ID (string) generated and stored on the host when the agent was installed.

• Host Machine ID: The unique ID (string) of the host, collected from the host OS.

Edit Agent Drawer

Use the Edit Agent drawer, accessible via the Edit button in the Agent Details Drawer, to view and change details of your installed Universal Agents.

The Edit Agent drawer includes the following UI elements:

• Cancel (button): Closes the drawer without saving any changes.

• Save (button): Saves changes to agent settings and exits the drawer.

• Name: Your organization's name for the agent (defaults to host name).

• Description: An optional, user-provided description of the agent.

• Closest Network Device (NMS only): A drop-down with which to specify the device in your network that is the fewest hops from the host on which the agent is installed.

  Note: This setting facilitates topology-aware device status reporting in NMS.

• Site: A field showing the site, if any, to which the agent is currently assigned, which could be a data center or a VPC in a cloud provider (see About Sites). To set or change the site, click in the field to drop down a filterable list of sites, then click on a site in the list to select it.

• Create a New Site (button): If a site hasn't yet been defined for the location where the agent host is located, click the button to create a new site (see Configure Site Fields).

Configure Site Fields

When you click the Create a New Site button, the following fields are added to the Edit Agent drawer to enable you to enter the information required to create a new site:

• Site Name: A name for the new site.

• Street Address: The physical location of the new site, given as a street address.

• Use an Existing Site: If you decide not to create a new site, click this button to hide the Configure Site fields and instead choose a site from the Site drop-down.

Capability Drawer

The Capability drawer, which opens by clicking Details on an agent capability, has the following UI elements:

• Back/Cancel (button): Closes the drawer without saving any changes.

• Save (button): Saves changes and exits the drawer.

• Status: The capability status (e.g., "Up").

• Version: The version number for the capability, as distinct from the agent version, e.g., "v1.109.0".

• Binary: The binary name installed for this capability (e.g., "kdns").

• Run State: A description of how long the capability has been enabled (e.g., "Running since 2025-05-28 10:00 as pid 762"). If capability is disabled, this will be blank.

• Interface (DNS OTT Tap only): Indicates which interfaces are included, e.g., "All", "eth0, "lo", "gre0", or "gre101" (see Edit a Capability).

• Promiscuous Mode (DNS OTT Tap only): "True" if promiscuous mode is enabled, otherwise "False" (see Edit a Capability).

• Metrics chart(s): Varying by capability as follows:

  • NMS: Metrics per second

  • DNS OTT Tap: DNS Responses per second, Discards per second

  • SNMP Trap Receiver: Traps per second, Receiver errors per second

  • Syslog Server: Messages per second, Dropped messages per second

• View in Metrics Explorer: Opens the view in Metrics Explorer

• Devices (NMS only): Lists the devices for which NMS capability is collecting metrics, if any. Click the device name to open its details page. If no devices are found, "No devices found" is displayed.

• Enable/Disable this Capability: Click to enable/disable the capability.

Tip: In addition to using the button in the Capability drawer, you can enable/disable capabilities with the toggle switches in the Agent Details drawer (see Agent Details UI).