What's New
Product Documentation
Installing Enterprise Agents on Cisco Catalyst 9000 Series Switches
This article details the steps to install a ThousandEyes Enterprise Agent Docker container on a Cisco Catalyst 9000-series switch running IOS XE, using the command line. The agent is a signed ThousandEyes Docker image that can be quickly launched using Cisco application hosting. The agent can also be installed using the Cisco DNA Center orchestrator.

Requirements

In order to do the steps outlined in this article, you must have the following in place:
    A Cisco Catalyst 9000-series switch running the supported IOS XE version:
      Catalyst 9300 requires 17.3.3
      Catalyst 9400 requires 17.5.1
    Cisco DNA Advantage or DNA Premier licensing, to enable application hosting. (See Application Licensing.)
    500 MB of available memory per installed appliance. (See IOX Application Resource Limitations.)
    4 GB of free space on the bootflash. To verify the amount of free space on bootflash:
    1
    Dut1#dir bootflash: | include total
    2
    11353194496 bytes total (5859037184 bytes free)
    Copied!
    Knowledge of the vlan where the internet gateway for this app connects to the internet.
    Familiarity with Cisco Catalyst IOS XE application hosting. (See Application Hosting.)

Installation Steps

The installation process consists of the following steps:

Downloading the Docker Image

Download the Docker image from the ThousandEyes dashboard and copy it to your Cisco switch using SCP, FTP, TFTP, or USB storage.
If the switch has internet access, download the image directly onto the switch. Download the package from the ThousandEyes downloads site.
    1.
    Log in to the ThousandEyes platform using a login belonging to the account group that will be associated with the appliance.
    2.
    Go to Cloud & Enterprise Agents > Agent Settings and click Add New Enterprise Agent.
    3.
    Download the .tar file with the ThousandEyes appliance for Catalyst 9000-series switches.
    4.
    Use SCP, FTP, TFTP, or USB storage to copy the signed Docker image to the switch's flash: directory.
    1
    copy scp://[email protected]/thousandeyes-enterprise-agent-3.0.cat9k.tar flash:
    Copied!
    5.
    Run a checksum (md5) command to verify that the package transfer was successful. The md5 output should match 66c9ddf64575de515a1305a1c682d8fe:
    1
    catalyst#verify /md5 flash:thousandeyes-enterprise-agent-3.0.cat9k.tar
    2
    -----------------------------------------------------------
    3
    verify /md5 (flash:thousandeyes-enterprise-agent-3.0.cat9k.tar) = 66c9ddf64575de515a1305a1c682d8fe
    Copied!

Installing the Docker Container

    1.
    Enable the IOx framework on the switch:
    1
    Enter configuration commands, one per line. End with CNTL/Z.
    2
    catalyst(config)#iox
    3
    catalyst(config)#end
    Copied!
    2.
    Wait until all the services are running:
    1
    catalyst#show iox-service
    2
    ​IOx Infrastructure Summary:
    3
    ---------------------------
    4
    IOx service (CAF) 1.11.0.5 : Running
    5
    IOx service (HA) : Running
    6
    IOx service (IOxman) : Running
    7
    IOx service (Sec storage) : Not Running
    8
    Libvirtd 1.3.4 : Running
    9
    Dockerd 18.03.0 : Running
    10
    Application DB Sync Info : Available
    11
    Sync Status : Disabled
    Copied!
    3.
    Run the install command:
    catalyst#app-hosting install appid <app-name> package flash:thousandeyes-enterprise-agent-3.0.cat9k.tar
    Specify your desired app name and the location of the image file you want to use. In this example, we use thousandeyes_enterprise_agent.
    4.
    If the image is hosted on an HTTPS server, you can run the following command to download the image:
    1
    catalyst#app-hosting install appid <app-name> package https://downloads.thousandeyes.com/enterprise-agent/thousandeyes-enterprise-agent-3.0.cat9k.tar
    Copied!
    5.
    Your application should now be installed. You can check on it by running the following:
    1
    catalyst#sh app-hosting list
    2
    App id State
    3
    thousandeyes_enterprise_agent DEPLOYED
    Copied!

Configuring the Docker Container

Docker supports both guest IP address assignment and dynamic IP address assignment. You must configure a single virtual network interface card (vNIC) for the appliance.
    1.
    Verify that the front panel data port is running, with Layer-2 VLAN allowed from uplink:
    1
    interface GigabitEthernet1/0/13
    2
    description Uplink MGMT
    3
    switchport access vlan 21
    Copied!
    2.
    Create an SVI (Switch Virtual Interface) that matches with Layer-2 VLAN:
    1
    interface Vlan21
    2
    ip address 10.100.21.13 255.255.255.0
    Copied!
    3.
    Configure the AppGigabitEthernet port to allow Layer-2 VLAN:
    1
    interface AppGigabitEthernet1/0/1
    2
    switchport trunk allowed vlan 21
    3
    switchport mode trunk
    Copied!
    4.
    Configure the application, either with a static IP or with DHCP IP.
    Configuration with Static IP
    Use a guest IP address to assign a static IP address. In this example, assign 10.100.21.222/24, under VLAN 21 and use Google resolver:
    1
    catalyst(config)#app-hosting appid thousandeyes_enterprise_agent
    2
    catalyst(config-app-hosting)#app-vnic AppGigabitEthernet trunk
    3
    catalyst(config-config-app-hosting-trunk)#vlan 21 guest-interface 0
    4
    catalyst(config-config-app-hosting-vlan-access-ip)#guest-ipaddress 10.100.21.222 netmask 255.255.255.0
    5
    catalyst(config-config-app-hosting-vlan-access-ip)#exit
    6
    catalyst(config-config-app-hosting-trunk)#exit
    7
    catalyst(config-app-hosting)#app-default-gateway 10.100.21.1 guest-interface 0
    8
    catalyst(config-app-hosting)#name-server0 8.8.8.8
    9
    catalyst(config-app-hosting)#name-server1 8.8.4.4
    Copied!
    Next, set up the required Docker run options to specify account token. If you want to specify a hostname other than the switch's name, do this here as well:
    1
    catalyst(config-app-hosting)#app-resource docker
    2
    catalyst(config-app-hosting-docker)#prepend-pkg-opts
    3
    catalyst(config-app-hosting-docker)#run-opts 1 "-e TEAGENT_ACCOUNT_TOKEN=<Token>"
    4
    catalyst(config-app-hosting-docker)#run-opts 2 "--hostname Cisco-Docker"
    5
    catalyst(config-app-hosting)#start
    6
    catalyst(config-app-hosting)#end
    Copied!
    Configuration with DHCP IP
    Make sure the DHCP server is running on the layer-2 VLAN. In this case, assign a DHCP address under VLAN 21 and use Google resolver:
    1
    catalyst(config)#app-hosting appid thousandeyes_enterprise_agent
    2
    catalyst(config-app-hosting)#app-vnic AppGigabitEthernet trunk
    3
    catalyst(config-config-app-hosting-trunk)#vlan21 guest-interface 0
    Copied!
    Next, set up the required Docker run options to specify the account token. If you want to specify a hostname other than the switch's name, do this here as well:
    1
    catalyst(config-config-app-hosting-vlan-access-ip)#app-resource docker
    2
    catalyst(config-app-hosting-docker)#prepend-pkg-opts
    3
    catalyst(config-app-hosting-docker)#run-opts 1 "-e TEAGENT_ACCOUNT_TOKEN=<Token>"
    4
    catalyst(config-app-hosting-docker)#run-opts 2 "--hostname Cisco-Docker"
    5
    catalyst(config-app-hosting-docker)#name-server0 8.8.8.8
    6
    catalyst(config-app-hosting)#start
    7
    catalyst(config-app-hosting)#end
    Copied!
    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:
    1
    catalyst#wr mem
    2
    Building configuration...
    3
    [OK]
    Copied!

Verifying That the Docker Container Is Running

With the (config-app-hosting)#start command, the Docker container should have been started and should be running.
    1.
    Verify this by running the following:
    1
    catalyst# sh app-hosting list
    2
    App id State
    3
    ---------------------------------------------------------
    4
    thousandeyes_enterprise_agent RUNNING
    Copied!
    2.
    Verify the Docker container’s details:
    1
    catalyst#show app-hosting detail appid thousandeyes_enterprise_agent
    2
    App id : thousandeyes_enterprise_agent
    3
    Owner : iox
    4
    State : RUNNING
    5
    Application
    6
    Type : docker
    7
    Name : thousandeyes/enterprise-agent
    8
    Version : 3.0
    9
    Description :
    10
    Path : flash:thousandeyes-enterprise-agent-3.0.cat9k.tar
    11
    URL Path :
    12
    Activated profile name : custom
    13
    14
    Resource reservation
    15
    Memory : 500 MB
    16
    Disk : 1 MB
    17
    CPU : 1850 units
    18
    VCPU : 1
    19
    Attached devices
    20
    Type Name Alias
    21
    ---------------------------------------------
    22
    serial/shell iox_console_shell serial0
    23
    serial/aux iox_console_aux serial1
    24
    serial/syslog iox_syslog serial2
    25
    serial/trace iox_trace serial3
    26
    27
    Network interfaces
    28
    ---------------------------------------
    29
    eth0:
    30
    MAC address : 52:54:dd:d:38:3d
    31
    Network name : mgmt-bridge-v21
    32
    Docker
    33
    ------
    34
    Run-time information
    35
    Command :
    36
    Entry-point : /sbin/my_init
    37
    Run options in use : -e TEAGENT_ACCOUNT_TOKEN=TOKEN_NOT_SET
    38
    --hostname=$(SYSTEM_NAME) --cap-add=NET_ADMIN --mount
    39
    type=tmpfs,destination=/var/log/agent,tmpfs-size=140m --mount
    40
    type=tmpfs,destination=/var/lib/te-agent/data,tmpfs-size=200m -v
    41
    $(APP_DATA)/data:/var/lib/te-agent -e TEAGENT_PROXY_TYPE=DIRECT -e
    42
    TEAGENT_PROXY_LOCATION= -e TEAGENT_PROXY_USER= -e
    43
    TEAGENT_PROXY_AUTH_TYPE= -e TEAGENT_PROXY_PASS= -e
    44
    TEAGENT_PROXY_BYPASS_LIST= -e TEAGENT_KDC_USER= -e TEAGENT_KDC_PASS=
    45
    -e TEAGENT_KDC_REALM= -e TEAGENT_KDC_HOST= -e TEAGENT_KDC_PORT=88 -e
    46
    TEAGENT_KERBEROS_WHITELIST= -e TEAGENT_KERBEROS_RDNS=1 -e PROXY_APT=
    47
    -e APT_PROXY_USER= -e APT_PROXY_PASS= -e APT_PROXY_LOCATION= -e
    48
    TEAGENT_AUTO_UPDATES=1 -e
    49
    TEAGENT_ACCOUNT_TOKEN=nfhjzm8e8ikg07d4n31wcsws9bakcloh --hostname
    50
    Cisco-Docker
    51
    52
    Package run options : -e TEAGENT_ACCOUNT_TOKEN=TOKEN_NOT_SET
    53
    --hostname=$(SYSTEM_NAME) --cap-add=NET_ADMIN --mount
    54
    type=tmpfs,destination=/var/log/agent,tmpfs-size=140m --mount
    55
    type=tmpfs,destination=/var/lib/te-agent/data,tmpfs-size=200m -v
    56
    $(APP_DATA)/data:/var/lib/te-agent -e TEAGENT_PROXY_TYPE=DIRECT -e
    57
    TEAGENT_PROXY_LOCATION= -e TEAGENT_PROXY_USER= -e
    58
    TEAGENT_PROXY_AUTH_TYPE= -e TEAGENT_PROXY_PASS= -e
    59
    TEAGENT_PROXY_BYPASS_LIST= -e TEAGENT_KDC_USER= -e TEAGENT_KDC_PASS=
    60
    -e TEAGENT_KDC_REALM= -e TEAGENT_KDC_HOST= -e TEAGENT_KDC_PORT=88 -e
    61
    TEAGENT_KERBEROS_WHITELIST= -e TEAGENT_KERBEROS_RDNS=1 -e PROXY_APT=
    62
    -e APT_PROXY_USER= -e APT_PROXY_PASS= -e APT_PROXY_LOCATION= -e
    63
    TEAGENT_AUTO_UPDATES=1
    64
    65
    Application health information
    66
    Status : 0
    67
    Last probe error :
    68
    Last probe output :
    Copied!
    3.
    In the ThousandEyes platform, go to Cloud & Enterprise Agents > Agent Settings and verify the Docker container’s IP address:

Assigning the Agent to Tests

Now that you have installed, configured, and started your Docker-based agent, you can create tests and assign them to be run by your new agent. For instructions, see Getting Started with Tests.

Reconfiguring the Docker Container

    1.
    Stop the application:
    1
    catalyst# app-hosting stop appid thousandeyes_enterprise_agent
    2
    thousandeyes_enterprise_agent stopped successfully
    3
    Current state is: STOPPED
    Copied!
    2.
    De-activate the application:
    1
    catalyst# app-hosting deactivate appid thousandeyes_enterprise_agent
    2
    thousandeyes_enterprise_agent deactivated successfully
    3
    Current state is: DEPLOYED
    Copied!
    3.
    Modify the Docker options, and exit three times:
    1
    catalyst(config)#app-hosting appid thousandeyes_enterprise_agent
    2
    catalyst(config-app-hosting)#app-resource docker
    3
    catalyst(config-app-hosting-docker)#prepend-pkg-opts
    4
    catalyst(config-app-hosting-docker)#<run-opts command>
    5
    catalyst(config-app-hosting-docker)#exit
    6
    catalyst(config-app-hosting)#exit
    7
    catalyst(config)#exit
    Copied!
    4.
    Reactivate the application, and confirm that it’s activated:
    1
    catalyst# app-hosting activate appid thousandeyes_enterprise_agent
    2
    thousandeyes_enterprise_agent activated successfully
    3
    Current state is: ACTIVATED
    Copied!
    5.
    Start the application, and confirm that it is running:
    1
    catalyst# app-hosting start appid thousandeyes_enterprise_agent
    2
    thousandeyes_enterprise_agent started successfully
    3
    Current state is: RUNNING
    Copied!

Frequently Asked Questions

What is the expected NTP behavior for a Catalyst 9000 series deployed Enterprise agent?
The enterprise agent on a Catalyst 9000 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.
Last modified 1mo ago