Deploying Enterprise Agents

Introduction
The Enterprise Agent is a vantage point that is used to test targets from inside your
network or from an infrastructure that is within your control. You can easily install it
within your environment by deploying a virtual appliance, a Docker container, or a
Linux package that is installed on a supported Linux distribution. With the latest
software updates you can also run it on your Cisco Catalyst 9000 Series Switches.

Enterprise Agent Operation

The Enterprise Agent is a Linux server that is running custom Cisco ThousandEyes
software that checks in regularly with the agent collector to obtain instructions from the
Cisco ThousandEyes platform.

The Enterprise Agent performs the following tasks during an operation:

• Wake up, resolve the assigned hostname of the collector, and perform a handshake.
• Check for results that have not yet been synchronized with the agent collector.
• Synchronize results with the agent collector.
• Check current software version against available version.
1. Initiate update process if needed.
• Get new task information and go to sleep until the next task needs to be run.

Which test data information type is exchanged between an agent and the collector
largely depends on which kind of test is being run from the Cisco ThousandEyes agent.
In general, an agent will collect timing information for each phase of a test request and
information about each routable device, or often called node, touched in the path
between the agent and the test destination and the links that connect these nodes.

During a test and between check-ins with the agent collector, the Enterprise Agent
stores all information locally before uploading to the collector. Once the information
has been synchronized with the collector, it is removed from the agent.

The agent will also periodically determine if updates of the ThousandEyes software that
is running on an agent are needed. In a situation like this, the agent will silently perform
the upgrade process automatically. You, as an administrator, are only responsible to
perform a manual upgrade in a scenario when an operating system or environment in
which the agent is running is approaching the end of the support date.
Enterprise Agent Firewall Requirements
You can install the Cisco ThousandEyes Enterprise Agent behind a firewall or on a
network device that has access control lists (ACLs) configured. When installing the
agent, you must configure the device with rules that allow the Enterprise Agent to
register with the Cisco ThousandEyes platform, execute tests, report test results, and
access necessary infrastructure services such as the Domain Name Server (DNS),
Network Time Protocol (NTP) server, and repositories for software package updates.
Protocol
Destination Direction Notes
and Port
TCP&UDP
Configured DNS server Outbound DNS
53
Time
UDP 123 Configured NTP server Outbound
synchronization
c1.thousandeyes.com, sc1.thousandeyes.com,
ntrav.thousandeyes.com,
ThousandEyes
TCP 443 crashreports.thousandeyes.com, bbot-sentry- Outbound
Agent infrastructure
proxy.thousandeyes.com, data1.agt.thousandeyes.com,
api.thousandeyes.com, apt.thousandeyes.com
Used for software
archive.ubuntu.com security.ubuntu.com
TCP 80 Outbound updates on Ubuntu
archive.canonical.com ports.ubuntu.com*
based systems
TCP 22,
Enterprise Agent Inbound Management
443
Note
* ports.ubuntu.com requirement is only applicable to the Raspberry Pi based Enterprise
Agent.

The table lists port requirements for installation and operation of an Enterprise Agent.
Direction assumes that you are using stateful filtering on a security appliance, which
permits response packets automatically. If your device uses static rules, you must allow
the return traffic as well.

Certain agent installation types require additional connectivity when you perform the
agent installation process. The following table lists the requirements for Docker
installation and other Linux-based operating system flavors.

Protocol
Destination Direction Notes
and Port
hub.docker.com auth.docker.io registry.docker.io Docker-based agents
TCP 443 Outbound
production.cloudflare.docker.com (installation only)
RHEL, CentOS, and Oracle
TCP 443 yum.thousandeyes.com Outbound Linux-based agents
(installation only)
For an up-to-date list of connectivity requirements, you should also refer to the official
documentation at https://docs.thousandeyes.com/product-documentation/global-
vantage-points/enterprise-agents/configuring/firewall-configuration-for-enterprise-
agents.

Enterprise Agent Firewall Requirements (Tests)

Protocol and Port Destination Direction Notes
TCP/UDP 53 Outbound DNS Server Test and Queries
TCP 80, 443 Outbound Web Tests
TCP/UDP 5060 Outbound SIP Server Tests
Path Visualization, ICMP-based
ICMP Outbound
tests
TCP&UDP 9119, NAT traversal for Agent-to-
ntrav.thousandeyes.com Outbound
9120 Agent tests
RTP Stream Test (port
UDP 49152 (default) other agents Inbound/Outbound
configurable)
TCP&UDP 49153 Agent-to-Agent Test (port
other agents Inbound/Outbound
(default) configurable)

The rules you must configure to permit test traffic will depend on the type of tests you
select and the test target. In most tests, direction will be outbound from the agent.
Important exceptions are agent-to-agent tests where rules in both outbound and inbound
directions may be needed.

The table lists default ports for described test types. If you configure a test with a
nondefault port, it must be allowed in the security rules instead of the default value as
well.

It is also recommended that you permit all Internet Control Message Protocol (ICMP)
error message types inbound to the agent to ensure full network functionality. If your
firewall is stateful for all ICMP error response types, then no rules are required. For
firewalls that do not dynamically allow ICMP error messages in response to packets
sent outbound that encounter the error conditions, you should allow the following ICMP
types in the inbound direction.

Protocol ICMP Types

IPv4 3, 11
IPv6 1-4, 129

If the listed ICMP packets get filtered at the firewall, it will impact how Cisco
ThousandEyes can visualize network Path Visualization.

Enterprise Agent Network Utilization

 When you deploy the Cisco ThousandEyes Enterprise Agent within your own
infrastructure, you may want to understand how much network capacity will be utilized
by the agent when performing different tests.

Example test traffic in a single test round.

Test Type Packets Bytes

Agent-to-server (TCP) 245 27346
Agent-to-server (TCP without SACK) 306 30757
Agent-to-server (TCP+bandwidth) 806 485368
Agent-to-server (ICMP) 194 28280
DNS server 16 1632
DNS trace 10 1637

The table lists measured sums of traffic from an Enterprise Agent and responses from
the test targets using default test settings. Web layer tests like page load or transaction
tests are not listed as examples, as the amount of traffic heavily depends on the test
target. In other words, the size of the target web destination retrieved in a test round will
have a direct impact on the amount of traffic exchanged between the target and the
agent.

In addition to network utilization from a test, an agent also generates additional

overhead traffic with protocols like NTP and DNS, and for communication with the
ThousandEyes collector. However, such traffic will contribute very little to the overall
network utilization. A rare exception is the communication between the agent and
software repositories, when checking and downloading new software updates. But such
an action does not happen frequently—only once every few weeks or months and lasts
for a short span of time.

Enterprise Agent Deployment Options

The Enterprise Agent provides a vantage point from inside your network infrastructure.
There are several different deployment options available to fit your environment needs.

Software-based agents:

• Virtual Appliance (VMware, Microsoft Hyper-V, Oracle VirtualBox, Xen)

• Linux package (Ubuntu, Red Hat Enterprise Linux, CentOS)
• Docker

Hardware-based agents:

• Cisco IOS XE-based platforms

1. Standard Kernel Virtual Machine (KVM)-based agent (requires a Solid State
Drive [SSD] module)
 2. Embedded Docker based agent (IOS XE 17.3.3 or newer on supported
platforms)
• Intel NUC
• Raspberry Pi 4

Software-Based Agents
Most common software-based agent form factor is a virtual appliance that can be easily
installed in one of the supported hypervisors. It is a lightweight all-in-one package that
contains a web-based management interface for initial configuration.

You can run the Linux-package Enterprise Agent on any compatible version of Linux.
When you install and configure the package, it will run as a service. Cisco
ThousandEyes will automatically update the agent code, while it is your responsibility
to keep the operating system on a host server on supported versions.

Docker containers are lightweight virtualized environments that can run the
ThousandEyes Enterprise Agent. Docker containers require smaller overhead compared
to virtual machines with a full guest operating system running in a hypervisor. While a
Linux package Enterprise Agent deployment is restricted to Ubuntu, Red Hat Enterprise
Linux, CentOS, and Oracle Linux distributions, the Docker environment can be run on a
much wider variety of 64-bit Linux distributions.

Hardware-Based Agents
You can deploy the Enterprise Agent on Cisco IOS XE-based devices in two different
ways. On Cisco 4000 Series Integrated Services Routers (ISR), Cisco ASR 1000-Series
Aggregation Services Routers, and Cisco Catalyst 9300 series switches you can deploy
a KVM-based standard agent when running IOS XE 16.12.1 or a newer release. To
support the agent, these devices require an SSD module.

The second option was introduced with the Cisco IOS XE Release 17.3.3, which
supports running the embedded agent as a docker container on the Cisco Catalyst 9300
Series switches without the need for an extra SSD module.

When you need a turnkey solution, agents can be also installed on a commercially
available hardware such as Intel NUC or Raspberry Pi 4. This provides a convenient
form factor that you can easily ship to branch offices, partner sites, or other
environments, where provisioning only requires power and network connectivity. Refer
to the official documentation at https://docs.thousandeyes.com/product-
documentation/global-vantage-points/enterprise-agents/installing/installing-a-physical-
appliance for the latest list of supported hardware.

Enterprise Agent on Cisco IOS XE

Platforms
 The capability to run the Cisco ThousandEyes Enterprise Agent on Cisco IOS XE
devices enables you to quickly deploy agents on existing Cisco networking devices.
Standard Agent Embedded Agent
Cisco IOS XE
16.12.1+ 17.3.3+
requirements
17.3.3—Catalyst 9300/9300L Series
Supported Cisco ISR4000 / ASR 1000 routers
switches 17.5.1—Catalyst 9400 Series
devices Catalyst 9300 Series switches
switches
Resource
CPU: 2 vCPU Memory: 2 GB CPU: 1 vCPU Memory: 500 MB
requirements
Requires SSD
Yes Optional
module
BrowserBot Supported Planned support with installed SSD module
Virtualization
KVM Docker container
method

Supported Cisco hardware devices with a local SSD storage (NIM-SSD or MSATA-
SSD module) allows you to run a KVM-based Enterprise Agent. Support on routers was
introduced with Cisco IOS XE Release 16.1, while Catalyst switches support it from the
Cisco IOS XE Release 16.12.1. The standard agent also supports the BrowserBot
functionality, which allows you to execute page load and transactions tests, which are
storage-intensive tasks.

In many existing customer deployments, networking devices do not include an optional

SSD storage module. Therefore, Cisco IOS XE Release 17.3.3 brought support for an
embedded agent, which runs as a docker container on Catalyst 9000 Series switches and
does not require an optional storage module. This allows you to deploy an agent on a
larger number of existing Catalyst switches. Keep in mind that for BrowerBot-based
tests an SSD module is still a requirement.

Virtual Appliance Setup

The virtual appliance is a virtual machine containing a pre-built Cisco ThousandEyes
Enterprise Agent, which you can quickly deploy into a supported virtualization
hypervisor.
• Resource requirements:
1. 2 vCPUs
2. 2 GB of memory
3. 20 GB of storage
4. Internet connectivity
• Installation steps:
1. Obtain virtual appliance software (OVA).
2. Import appliance into supported hypervisor.
3. Assign dedicated or bridged network connection.
4. Perform initial configuration.
 The Virtual Appliance installation process consists of two parts. Once you validate
resource requirements, you first need to import the appliance into your selected
virtualization hypervisor. You can download the needed software from the
ThousandEyes portal under the Add New Enterprise Agent section.

When performing appliance import, make sure you either assign a dedicated network
interface to the agent, or configure it as a bridged network connection. Avoid setting
connectivity via the Network Address Translation (NAT) interface because it can hinder
agent capabilities.

Virtual Appliance Initial Configuration

Once you successfully import the appliance and power it on, you will need to perform
the initial configuration.

Configuration steps:

1. Access console to configure network settings if no DCHP is used.

2. Access appliance web interface using default credentials (username: admin, password:
welcome).
3. Specify account group token to link agent to your organization.
4. Configure NTP server.
5. Optionally configure proxy settings or run diagnostics.

If an appliance successfully obtained its network settings via the DHCP protocol, a
management console will display an obtained IP address together with the default login
credentials. In environments without the DHCP server, you will need to manually
assign the IP address, gateway, broadcast address, DNS, and IPv6 address settings.

Once your newly deploy agent has network connectivity, you can continue with initial
configuration over its web interface.

First, you will need to change the default password. The newly selected password must
be at least eight characters long and must contain at least three of the following types of
characters: digits, lowercase letters, uppercase letters, and symbols.

In an upcoming step, you need to define an account group token, which links a new
agent with your organization. You can obtain your unique organization token within the
ThousandEyes portal, under the Add New Enterprise Agent section.

You also need to configure the NTP server. Accurate time on an agent is very
important, so that test data gets correctly time-stamped and synchronized.
Many organizations secure internet connectivity by redirecting the web traffic via
proxy. If redirection does not happen transparently, you may need to explicitly
configure proxy settings.

After you configure the listed configuration steps, the agent should be able to
successfully register to the ThousandEyes portal. If there are issues, you can use a
diagnostics tool, which will help you determine unreachable or misconfigured services
like DNS or NTP for example.

Custom Virtual Appliance

Custom virtual appliance is a purpose-built virtual appliance, which is preconfigured
with the account group token and Secure Shell Protocol (SSH) keys used for
management. This allows you to streamline a deployment process when installing a
larger number of virtual appliances.

You can generate a custom virtual appliance under the Add New Enterprise
Agent section, under the Custom Appliance tab.

First, you need to define Appliance Type and Format. Choose the OVA format for
VMware or Oracle VirtualBox hypervisor, while you should use the ZIP format when
deploying a custom appliance in Microsoft Hyper-V. Choose Cisco OVA when
deploying a Cisco IOS XE KVM-based appliance on supported Cisco platforms.

Optionally, you can also specify proxy details, in case explicit configuration is needed.

Use your favorite SSH keys generator to generate a public and private SSH key pair.
Paste the generated public key into the form, while you safely store your private key.
You will need it every time you want to connect to the custom appliance over SSH for
maintenance or troubleshooting.