What's New
Product Documentation

Docker Agent Installation for Cisco Routers

This article provides an overview of the steps to install a ThousandEyes Enterprise Agent Docker container on a supported Cisco router running IOS XE. The agent is a signed ThousandEyes Docker image that can be quickly launched using Cisco application hosting.

For routers running in SD-WAN mode managed through vManage, the agent can also be installed using vManage feature templates. For more information on vManage installation instructions, contact your Cisco account team for details.

Prerequisites

To review the supported Cisco routers and hardware requirements, see the Support Matrix.

Both SD-WAN and Autonomous mode are supported.

Overview

Deploying an Enterprise Agent on a Cisco router requires the completion of three steps. These steps are detailed in the sections below:

  1. Install the Enterprise Agent on the Cisco router, using one of three available methods (bootflash, direct, via local machine).

  2. Configure the container's networking and account information.

  3. Verify the agent is running.

Installation Methods

There are three installation methods available to customers.

For Cisco routers purchased before August 15th, 2021, the Docker image can be installed either directly from the ThousandEyes download servers, or by downloading the container image to a local machine and uploading it to the router via SCP, FTP, TFTP, or USB storage, depending on whether the router has direct Internet access or not.

Routers purchased after August 15th, 2021, can, in addition to the previous methods, install the Enterprise Agent via bootflash.

Install the Docker Image from Bootflash

If the router was purchased after August 15th, 2021, the router will have the ThousandEyes Enterprise Agent available in bootflash.

To verify if it is available, use the following command: Dut1#dir bootflash:/apps.

  1. Run the following command to install via bootflash:

    #app-hosting install appid package bootflash:apps/thousandeyes-enterprise-agent-4.0.2.cisco.tar

Install the Docker Image to the Router Directly

If the Cisco router has direct internet access, follow the steps below to install the Enterprise Agent:

  1. Run the following command to install the image:

    catalyst#app-hosting install appid <app-name> package https://downloads.thousandeyes.com/enterprise-agent/thousandeyes-enterprise-agent-4.0.2.cisco.tar
  2. Your application should now be installed. You can check on it by running the following:

    catalyst#sh app-hosting list
    App id State
    thousandeyes_enterprise_agent DEPLOYED

Install the Docker Image via a Local Machine

If the Cisco router does not have direct access to the Internet, follow the steps in the sections below to install the Enterprise Agent.

Download the Docker Image to a Local Machine

Download the Docker image from the ThousandEyes dashboard and copy it to your Cisco router using SCP, FTP, TFTP, or USB storage.

  1. On your local machine, log into the ThousandEyes platform using a login belonging to the account group that will be associated with the appliance.

  2. Navigate to Cloud & Enterprise Agents > Agent Settings and click Add New Enterprise Agent.

  3. Download the .tar file with the ThousandEyes appliance for Catalyst 8000-series or ISR 4000-series routers.

  4. Use SCP, FTP, TFTP, or USB storage to copy the signed Docker image to the router's flash: directory.

  5. Run the following command:

    copy scp://[email protected]/thousandeyes-enterprise-agent-4.0.2.cisco.tar flash:
  6. Run a checksum (md5) command to verify that the package transfer was successful. The md5 output should match 595513485b256c5e0fba4cec1b69e0b3.

    catalyst#verify /md5 (flash:thousandeyes-enterprise-agent-4.0.2.cisco.tar) = 595513485b256c5e0fba4cec1b69e0b3

Install the Docker Image from a Local Machine

  1. Enable the IOx framework on the router. Enter one configuration command per line, and end with CNTL/Z:

    catalyst(config)#iox
    catalyst(config)#end
  2. Wait until all the services are running:

    catalyst#show iox-service
    IOx Infrastructure Summary:
    IOx service (CAF) : Running
    IOx service (HA) : Not Supported
    IOx service (IOxman) : Running
    IOx service (Sec storage) : Not Supported
    Libvirtd 5.5.0 : Running
  3. Run the installation command, specifying your desired app name and the location of the image file you want to use. In this example, we use thousandeyes_enterprise_agent:

    catalyst#app-hosting install appid <app-name> package flash:thousandeyes-enterprise-agent-4.0.2.cisco.tar
  4. If the image is hosted on an HTTPS server, you can run the following command to download the image:

    catalyst#app-hosting install appid <app-name> package https://downloads.thousandeyes.com/enterprise-agent/thousandeyes-enterprise-agent-4.0.2.cisco.tar
  5. Your application should now be installed. You can check on it by running the following:

    catalyst#sh app-hosting list
    App id State
    thousandeyes_enterprise_agent DEPLOYED

Configuration

Docker supports both static IP address assignment and dynamic IP address assignment. You must configure a single virtual network interface card (vNIC) for the appliance using either a management interface or virtual port group interface.

VirtualPortGroup Interface

  1. Configure the VirtualPortGroup interface with a private IP address and use as NAT inside:

    (config)interface VirtualPortGroup0
    (config)ip address 10.100.152.100 255.255.255.0
    (config)ip nat inside
  2. Configure NAT outside on the physical port interface:

    (config)interface GigabitEthernet0/0/3
    (config) ip nat outside
  3. Create NAT rule:

    (config)ip nat inside source list NAT interface GigabitEthernet0/0/3 overload
    (config)ip access-list extended NAT
    (config)10 permit ip 10.100.152.0 0.0.0.255 any
  4. Configure the application, either with a static IP or with DHCP IP:

    a. Configuration with Static IP:

    Use a guest IP address to assign a static IP address. In this example, assign 10.100.152.120/24 from VirtualPortGroup 0 and use Google resolver:

    (config)#app-hosting appid c8200
    (config-app-hosting)#app-vnic gateway0 virtualportgroup 0 guest-interface 0
    (config-app-hosting-gateway0)#guest-ipaddress 10.100.152.120 netmask 255.255.255.0
    (config-app-hosting-gateway0)#app-default-gateway 10.100.152.100 guest-interface 0
    (config-app-hosting-docker)#name-server0 8.8.8.8
    (config-app-hosting)#end

    Next, set up the required Docker run options to specify account token. If you want to specify a hostname other than the router's name, do this here as well:

    catalyst(config-app-hosting)#app-resource docker
    catalyst(config-app-hosting-docker)#prepend-pkg-opts
    catalyst(config-app-hosting-docker)#run-opts 1 "-e TEAGENT_ACCOUNT_TOKEN=<Token>"
    catalyst(config-app-hosting-docker)#run-opts 2 "--hostname Cisco-Docker"
    catalyst(config-app-hosting)#start
    catalyst(config-app-hosting)#end

    b. Configuration with DHCP IP:

    Make sure the DHCP server is running on the VirtualPortGroup interface.

    (config)#app-hosting appid c8200
    (config-app-hosting)#app-vnic gateway0 virtualportgroup 0 guest-interface 0
    (config-app-hosting-docker)#name-server0 8.8.8.8
    (config-app-hosting)#end

    Next, set up the required Docker run options to specify the account token same as the static IP assignment example above. For a full list of the Docker configuration options, see Docker Agent Configuration Options.

  5. Exit three times to completely exit out of config mode.

  6. Use wr mem to ensure that your configuration changes have persisted across reboots:

    catalyst#wr mem
    Building configuration...
    [OK]

Verification

With the (config-app-hosting)#start command, the Docker container should have been started and should be running. You can verify this through the following options:

c8200# sh app-hosting list
App id State
thousandeyes_enterprise_agent RUNNING`

Verify the Docker container’s details:

c8200#sh app-hosting detail appid c8200
App id : c8200
Owner : iox
State : RUNNING
Application
Type : docker
Name : ThousandEyes Enterprise Agent
Version : 4.0.2
Description :
Author : ThousandEyes <[email protected]>
Path : bootflash:thousandeyes-enterprise-agent-4.0.2.cisco.tar
URL Path :
Activated profile name : custom
Resource reservation
Memory : 500 MB
Disk : 1 MB
CPU : 1850 units
CPU-percent : 48 %
VCPU : 1
Platform resource profiles
Profile Name CPU(unit) Memory(MB) Disk(MB)
--------------------------------------------------------------
Attached devices
Type Name Alias
---------------------------------------------
serial/shell iox_console_shell serial0
serial/aux iox_console_aux serial1
serial/syslog iox_syslog serial2
serial/trace iox_trace serial3
Network interfaces
---------------------------------------
Eth0:
MAC address : 52:54:dd:e9:9e:9f
IPv4 address : 10.100.152.122
IPv6 address : ::
Network name : VPG0

In the ThousandEyes platform, go to Cloud & Enterprise Agents > Agent Settings and verify the Docker container’s IP address.

Reconfigure the Docker Container

  1. Stop the application:

    catalyst# app-hosting stop appid thousandeyes_enterprise_agent
    thousandeyes_enterprise_agent stopped successfully
    Current state is: STOPPED
  2. De-activate the application:

    catalyst# app-hosting deactivate appid thousandeyes_enterprise_agent
    thousandeyes_enterprise_agent deactivated successfully
    Current state is: DEPLOYED
  3. Modify the Docker options, and exit three times:

    catalyst(config)#app-hosting appid thousandeyes_enterprise_agent
    catalyst(config-app-hosting)#app-resource docker
    catalyst(config-app-hosting-docker)#prepend-pkg-opts
    catalyst(config-app-hosting-docker)#<run-opts command>
    catalyst(config-app-hosting-docker)#exit
    catalyst(config-app-hosting)#exit
    catalyst(config)#exit
  4. Reactivate the application, and confirm that it’s activated:

    catalyst# app-hosting activate appid thousandeyes_enterprise_agent
    thousandeyes_enterprise_agent activated successfully
    Current state is: ACTIVATED
  5. Start the application, and confirm that it is running:

    catalyst# app-hosting start appid thousandeyes_enterprise_agent
    thousandeyes_enterprise_agent started successfully
    Current state is: RUNNING

Frequently Asked Questions

What is the expected NTP behavior for a Catalyst 8000 series deployed Enterprise agent?

The enterprise agent on a Catalyst 8000 series switch uses the host system kernel clock. It also sends packets to pool.ntp.org to determine any clock offset. It does not try to adjust the host or container clock but will adjust measurement timestamps based on the clock offset.

Can the default external NTP source (pool.ntp.org) be changed to a customer's internal NTP source?

No. The agent uses pool.ntp.org to determine clock offset by default; this is currently not configurable.