Cisco Catalyst - NetBeez App Hosting with Docker (IOS-XE 16.12+/17.x)

Cisco Solution Partner

cisco_tier_2_large.png NetBeez is a Cisco Preferred Solution Partner: the NetBeez agents are compatible with Cisco equipment. You can read more here.

Other NetBeez Cisco integrations are available on the online documentation:

Other resources:



This procedure assumes that you have the following resources:

  • Cisco Catalyst 9300/9400/9500
  • USB SSD-120G for the back panel USB port on the Catalyst 9300 switch (usbflash1:/)
    • Similar storage for Cisco Catalyst 9400
  • Cisco IOS-XE software version 16.12.1 (Release date: July 2019) or newer versions
    • show version
  • Cisco Network Advantage and DNA Advantage
    • show license summary
  • NetBeez dashboard
  • NetBeez docker agent v2.0.5 (nb-agent) or newer versions (available on Docker Hub)

 If you don't have an existing installation of NetBeez, you can request a demo here.



The procedure that follows will set up the following resources:

  • NetBeez docker container image
  • VLAN 123 and VLAN 123 routed interface
  • Gig 1/0/1 as uplink on the Catalyst
  • AppGigEthernet port


Before you begin ...

Verify that the USB SSD-120G flash storage is recognized by the Catalyst:

dir usbflash1:
Directory of usbflash1:/

11 drwx 16384 Mar 25 2019 22:32:36 +00:00 lost+found

118014062592 bytes total (105824313344 bytes free)

If the SSD is not recognized by the Catalyst, format it in ext2 on a Linux machine.


Step-by-step installation configuration

1. Download the NetBeez docker agent image on your local laptop.
Download the latest docker image of the NetBeez agent:
docker pull netbeez/nb-agent
Save the downloaded NetBeez docker agent as a tar archive:
docker save netbeez/nb-agent > netbeez.tar
You can now either copy the netbeez.tar to a USB thumb drive (option 2.1) or upload it to an scp server (option 2.2).
2. Log in to the Catalyst and copy the netbeez.tar archive to the thumb drive.
Option 1 Thumb drive - Copy the netbeez.tar from the USB thumb drive plugged in the front USB port of the catalyst:
copy usbflash0:netbeez.tar flash:
Option 2 Secure Copy - Secure copy (scp) the netbeez.tar from the scrp server to the Catalyst:
copy scp: flash:
Address or name of remote host []?
Source username [iox]?
Source filename []?
Destination filename [netbeez.tar]?
Sending file modes: C0644 522190336 netbeez.tar
522190336 bytes copied in 278.509 secs (1874950 bytes/sec)
3. Configure resources to provide network connectivity to the NetBeez docker agent. Please make sure that the VLAN assigned to the NetBeez app has a DHCP server or relay configured and can reach the server and the Internet (proxy supported).
a. Create the VLAN and VLAN interface:
vlan 123
no shutdown

conf t
interface Vlan123
ip address
b. Map the VLAN to the uplink port Gig 1/0/1:
interface GigabitEthernet1/0/1
switchport access vlan 123
switchport mode access
c. Configure the AppGigabitEthernet1/0/1 interface:
interface AppGigabitEthernet1/0/1
switchport trunk allowed vlan 123
switchport mode trunk
The above configuration allows VLAN 123 on the AppGigabitEthernet port while configuring it in trunk mode.
4. Enable and verify App Hosting.
a. Configure App Hosting:
conf t
b. Verify the status of App Hosting:
show iox-service
IOx Infrastructure Summary:
IOx service (CAF) : Running
IOx service (HA) : Running
IOx service (IOxman) : Running
Libvirtd : Running
Dockerd : Running
5. Configure the activation profile.
a. Map interface eth0 of the NetBeez docker agent to VLAN 123 on the AppGigabitEthernet 1/0/1 interface: 
conf t
app-hosting appid netbeez
app-vnic AppGigabitEthernet trunk
vlan 123 guest-interface 0
In case of static configuration, please add the following lines below the 'vlan 123 guest-interface 0' line (skip this section if you want your NetBeez app to use DHCP):
guest-ipaddress x.x.x.x netmask x.x.x.x
app-default-gateway x.x.x.x guest-interface 0
name-server0 x.x.x.x
6. Configure the agent to register to your NetBeez BeezKeeper Dashboard.
Option 1 - Auto-config with Internet (no proxy) using the secret key:
conf t
app-hosting appid netbeez
app-resource docker
run-opts 1 "-e 'NB_SECRET_KEY=<SECRET_KEY>' -v netbeez:/etc/netbeez/persistence/:rw"
With these options, the docker application will have the environment variable NB_SECRET_KEY set to the value set by<SECRET_KEY>.
Option 2 - Auto-config with the Internet via proxy using the secret key:
conf t
app-hosting appid netbeez
app-resource docker
run-opts 1 "-e 'NB_SECRET_KEY=<SECRET_KEY>' -e 'http_proxy=<HTTP_PROXY_ADDRESS_PORT>' -e 'https_proxy=<HTTPS_PROXY_ADDRESS_PORT>' -v netbeez:/etc/netbeez/persistence/:rw"
With these options, the docker application will have the environment variable NB_SECRET_KEY set to the value set by<SECRET_KEY>, and it will use the HTTP proxy HTTP_PROXY_ADDRESS_PORT and HTTPS proxy HTTPS_PROXY_ADDRESS_PORT; an example of proxy a server URI is
Option 3 - Manual configuration for an off-line network using an insecure connection:
conf t
app-hosting appid netbeez
app-resource docker
run-opts 1 "
-e 'HOST=<SERVER_IP_OR_FQDN>' -e 'PORT=20019' -v netbeez:/etc/netbeez/persistence/:rw"
With these options, the docker application will connect to port 20019 of the server define via FQDN or IP with variable <SERVER_IP_OR_FQDN>. Please keep in mind that this method, different from Options 1 and 2, causes the agent to connect to the server's port 20019, which is un-secure, rather than 20018, which is secured by SSL certificates.
More information about the available options can be found on our Docker Hub page here.
7. Configure the docker container resources: CPU, RAM, and disk.
conf t
app-hosting appid netbeez
app-resource profile custom
cpu 7400
memory 1000
persist-disk 4000
8. Install and activate the NetBeez docker agent cat9k application.
app-hosting install appid netbeez package flash:netbeez.tar

Installing package 'flash:netbeez.tar' for netbeez. Use 'show app-hosting list' for progress.
Verify that NetBeez docker agent is deployed:
show app-hosting list
App id State
netbeez DEPLOYED
 Activate the NetBeez docker agent application:
app-hosting activate appid netbeez
netbeez activated successfully
Current state is: ACTIVATED
Start the NetBeez docker agent application:
app-hosting start appid netbeez
netbeez started successfully
Current state is: RUNNING
Verify that the NetBeez docker agent application is running:
show app-hosting list 
App id                                   State
netbeez                                  RUNNING
9. Working with the app.
Access the app container console

One may access the app console for verifying the status of processes within the container.

app-hosting connect appid netbeez session

Check app resource utilization

show app-hosting utilization appid netbeez
Application: netbeez
CPU Utilization:
CPU Allocation: 7400 units
CPU Used: 1.49 %
Memory Utilization:
Memory Allocation: 2048 MB
Memory Used: 893 KB
Disk Utilization:
Disk Allocation: 4000 MB
Disk Used: 0.00 MB

10. Troubleshooting agent can't connect to the dashboard

If the agent is not showing on the dashboard, connect to it via the console:

app-hosting connect appid netbeez session

Then verify that is correctly configured with the server IP address and port:


Verify that the variables set in step 6 are correct, such as:

$NB_SECRET_KEY = <value>


$HOST = <value>
$PORT = <value>
Have more questions? Submit a request


Article is closed for comments.