Universal Agents

The Universal Agents page of the Kentik portal’s Settings section is covered in the following topics:

• About the Universal Agent
• Universal Agents Page
• Agent Details Drawer
• Edit Agent Drawer
• Capability Drawer
• Deploy the Universal Agent
• Edit a Universal Agent
• Edit a Capability

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), add features to the agent by installing Agent Capabilities.

Note: All Kentik agents (see Agents) will gradually be replaced with Agent Capabilities of the Kentik Universal Agent.

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:

Note: The DNS OTT Tap capability of the Universal Agent replaces kprobe as the method for tapping DNS data, as described in Enabling OTT DNS Collection.

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).

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).

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.

The Universal Agents List is a table that lists all 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).

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.

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).

The Agent Details drawer, accessible by clicking an agent's row in the Universal Agents List, is covered in the following topics:

• Agent Details UI
• Agent Details Fields

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 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 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.

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).

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.

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.

Note: 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).

The Deploy the Universal Agent dialog, accessible from the Deploy Agent button, enables you to deploy a new instance of the Universal Agent via Docker or Linux.

Follow these steps:

1. Under Installation, choose Docker or Linux and click the corresponding tab. The necessary command will appear in the text area below the tabs.
2. Click Copy to copy the command from the text area.
3. Open a terminal window on the host machine and paste the command. (To use a web proxy, see Install Agent via Web Proxy).
4. Run the command. The new agent will appear in the Select an Agent list. The Host Name column will vary as follows:
   - Docker: The agent's Docker container ID.
   - Linux: The hostname of the Linux system where the agent was installed.
5. Click Authorize to authorize the agent to connect with Kentik. The dialog will refresh with basic information, optional fields, and a Continue button.
   
6. Optionally add Display Name, Description, and Site Name. Click Continue to proceed.
7. Select the capabilities to enable for this agent by clicking the toggle switch next to each capability.
   
8. Click the Finish button to complete the deployment process. Once deployed, the agent will appear on the Universal Agents List.

Note: 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.

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

To edit a Universal Agent, follow these steps:

1. Navigate to the Universal Agents Page via Settings » Universal Agents in the 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.

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

1. Go to the Universal Agents Page via Settings » Universal Agents in the 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:
   - Update an Existing Argument: Select a different Command Line Value from the dropdown.
   - 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: