Connecting your IOS managed gateway devices to Cisco Webex Control Hub, allows you to manage and monitor them from anywhere, together with the rest of your Unified Communications infrastructure. Moreover, this enables you to initiate common tasks to manage your devices more effectively. To enroll a gateway, you have to install a management connector application and make sure that there is a secure connection between this and the Cisco Webex cloud. After you establish this connection, you can enroll the gateway by logging in to the Control Hub.
About managed gateways
Enrolling your Cisco IOS gateways to Control Hub helps you to simplify device management and allows you to benefit from new Webex Calling services. As gateways maintain a connection with Control Hub, you can manage and monitor them from anywhere, along with the rest of your Webex Calling devices.
This process does not apply to Cisco IOS Voice Gateways, such as the VG400, which are fully managed as devices in Control
Hub.
|
The connection from the gateway to Control Hub is established and maintained by small connector applications, which run in a virtual Linux enviroment within the gateway, known as the Guest Shell. The Guest Shell and connector applications are configured and setup using a simple-to-follow script, which is run on the gateway from the Webex cloud during the enrollment process.
To simplify the installation process, the script adds a number of necessary gateway configurations. Details of these commands are provided in the subsequent section.
Gateway connectors are small applications that run in the gateway Guest Shell to maintain a connection to Control Hub, co-ordinate events and collect status information.
The gateway connectors are installed on the Cisco IOS XE Guestshell container.
If you are interested in finding out more about the GuestShell feature, visit https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/173/b_173_programmability_cg/guest_shell.html. |
There are two types of connectors:
-
Management connector
-
Telemetry connector
An interactive menu-driven TCL script helps with the setting up of GuestShell, and installation and maintenance of the management connector.
The management connector takes care of gateway enrollment and lifecycle management of the telemetry connector.
After successful completion of enrollment, the management connector downloads and installs the latest telemetry connector.
The following graphic depicts how the different components are connected in a Webex Calling solution:

As part of TCL script execution, the following information is collected from the user:
-
External interface.
-
DNS server addresses.
-
Proxy details.
-
Connector IP address
-
Gateway Credentials (username and password)
The following are the configurations that are performed by the TCL script:
-
Virtual Port Group—Required for guestshell configuration.
-
Guestshell
-
NETCONF Yang
-
SNMP Trap configuration—Required for notifications from Cisco IOS XE.
-
IP Route—To route connector-related traffic through virtual port group.
The following is a sample of the configurations that are performed by the TCL script:
!
interface VirtualPortGroup 0
ip unnumbered GigabitEthernet1
no mop enabled
no mop sysid
!
!
app-hosting appid guestshell
app-vnic gateway0 virtualportgroup 0 guest-interface 0
guest-ipaddress 10.65.125.227 netmask 255.255.255.128
app-default-gateway 10.65.125.142 guest-interface 0
app-resource profile custom
cpu 800
memory 256
persist-disk 500
name-server0 72.163.128.140
name-server1 8.8.8.8
!
!
netconf-yang
netconf-yang cisco-ia snmp-trap-control trap-list 1.3.6.1.4.1.9.9.41.2.0.1
netconf-yang cisco-ia snmp-community-string Gateway-Webex-Cloud
!
!
logging snmp-trap emergencies
logging snmp-trap alerts
logging snmp-trap critical
logging snmp-trap errors
logging snmp-trap warnings
logging snmp-trap notifications
!
!
snmp-server community Gateway-Webex-Cloud RO
snmp-server enable traps syslog
snmp-server manager
!
!
ip route 10.65.125.227 255.255.255.255 VirtualPortGroup0
!
For the above sample configuration:
|
Before enrolling a gateway, do note that there is no support for the following:
-
Cisco 1100 Integrated Services Router platforms.
-
High Availability (HA) mode.
-
Controller or SD-WAN mode (Site Survivability only supports gateways running in Cisco IOS XE Autonomous mode).
-
Cisco IOS Voice Gateways, such as VG400, which is fully managed as devices in Control Hub.
The following are the prerequisites for enrolling a gateway:
-
Access to Control Hub as an organization administrator.
-
IP addresses, usernames, and passwords for the devices that you want to configure.
-
Cisco IOS XE Version:
-
Local Gateways—Cisco IOS XE Amsterdam 17.3.4a or later.
-
Survivability Gateways—Cisco IOS XE Cupertino 17.9.3a or later.
-
-
System Requirements:
-
Minimum free memory—256 MB
-
Minimum disk space—2000 MB (This includes 1100 MB for Guestshell container and 500 MB for connector applications). If an SSD (harddisk:) is installed, this will be used for the connector installation. In all other cases, System bootflash: will be used.
-
If you're using a router with 4GB of bootflash and less than 2GB of available capacity (the minimum capacity), delete all IOS binary (.bin) images, except the one that is currently running. After you delete files, free up additional space. Use the following steps to expand binary image and boot from components:
-
Create a new directory using mkdir bootflash:/image.
-
Expand the IOS binary image using: request platform software package expand file bootflash:/<image>.bin to bootflash:/image.
-
In configuration mode, remove current boot options using: no boot system.
-
Configure new boot statement: boot system bootflash:/image/packages.conf.
-
Exit from configuration mode, save configuration, and reboot.
-
Once the router has restarted, use show version to verify that the router booted from
bootflash:/image/packages.conf
. If yes:-
Verify that the
bootflash:/sysboot
directory is empty. -
Delete the remaining IOS binary image.
-
Delete any core images using delete /f /r bootflash:/core/*.
-
Delete tracelog files using delete /f /r bootflash:/tracelogs/*.
-
If there is still insufficient disk space, review any the remaining files in bootflash: and delete any other non-essential files such as logs and CDRs.
-
-
A supported Cisco router, which is connected to a network with a path to the internet. The basic configuration must have the following:
-
DNS server configured to resolve public domain names.
To configure the DNS server, use the following commands:
ip name-server <IP address>
-
HTTP Proxy server if you want to reach to the internet through a proxy.
-
To set a proxy server, use the following commands:
ip http client proxy-server <server address> proxy-port <port number>
-
If the proxy server needs authentication, use the following commands to authenticate:
ip http client username <username>
ip http client password <password>
-
-
Gateway credentials: Credentials (username and password) with privilege level 15 access that the connector can use to access the gateway through its NETCONF interface.
To authenticate and authorize NETCONF access, ensure that the default aaa lists are configured as illustrated below. You can use any method option in the default list. However, it's not possible to use a named aaa list to control NETCONF access. If the default lists are not configured correctly, you may see an "invalid method list" error message in the system log.
aaa new-model aaa authentication login default radius local aaa authorization exec default radius local if-authenticated username test privilege 15 secret <password>
The following are the network prerequisites:
-
The connector IP address must be in the same network as the one chosen for external connectivity. It can be a private network address, but it must have HTTP access to the internet.
-
You must have connectivity to the Control Hub and on-premises devices to complete the enrollment process.
-
URLs that need to be accessed for Webex services
-
*.ucmgmt.cisco.com
-
*.webex.com
-
*.wbx2.com
-
-
Transport protocols: Transport Layer Security (TLS) version 1.2.
-
Import the IOS public certificate authority bundle. The certificates added to the gateway trust pool are used to verify access to Webex servers. Use the following configuration command to import the bundle.
crypto pki trustpool import url http://www.cisco.com/security/pki/trs/ios.p7b
-
If you've already added the gateway to Control Hub and have installed the management connector, you can skip this procedure.
Go to Step 5 of Enroll the gateway to Control Hub to complete the enrollment process.
|
1 |
Sign in to Webex Control Hub at https://admin.webex.com/login. |
2 |
Under SERVICES, click Calling and then click the Managed Gateways tab.
|
3 |
Click the Add Gateway button. |
4 |
Copy the tclsh command that displays in the Add a Managed Gateway window. You must run the command on the gateway CLI as a part of the management connector installation procedure. |
What to do next
Go to the next procedure to install the management connector on the gateway.
You can resume the enrollment process in Control Hub after the connector is installed on the gateway.
Before proceeding with the installation of the management connector, make sure that you meet all the Prerequisites. |
Execute the script
Sign in to the gateway using a console or SSH connection, then paste the following string to the router exec command prompt:
tclsh https://binaries.webex.com/ManagedGatewayScriptProdStable/gateway_onboarding.tcl
|
Start the installation
If the connector is not set up already, the script takes you to the installation menu; else, to the home menu.
1 |
Choose the interface that is in the same network as the address reserved for the connector.
|
||||
2 |
Configure the DNS server to be used by the connector. By default the servers that are configured in IOS are used.
|
||||
3 |
If you need to use a proxy to access the internet, enter the proxy details when prompted. If the gateway has already been configured with a proxy, the following details are used by default. Select 'n' to override these settings, if required.
|
||||
4 |
Configure SNMP trap settings. To push notifications to the Cisco Webex cloud, the script updates the SNMP trap configuration level in the router if it is set below the notification level. The system prompts you to confirm whether to change the SNMP trap configuration to notification level. To retain the current SNMP trap configuration level, select N.
|
||||
5 |
Enter the connector IP address.
|
||||
6 |
Enter the username and password that the connector uses to access the router NETCONF interface.
|
||||
7 |
You get the "Cloud connector is installed successfully" message after the successful installation.
|
What to do next
Before you begin
1 |
Check that the Add a Managed Gateway window displays in Control Hub. If the window does not display, under SERVICES, click Calling, select the Managed Gateways tab, and click Add Gateway. ![]() |
||
2 |
In the Add a Managed Gateway window, check the I have installed the management connector on the gateway check box and click Next.
|
||
3 |
At the Add a Managed Gateway screen, enter the connector IP address that you entered during the connector installation procedure, and a preferred display name for the gateway |
||
4 |
Click Next. A browser tab that connects to the connector management page on the router opens so that you can complete the enrollment.
|
||
5 |
To log , enter the Gateway Admin Username and Password that you entered in step 6 of the connector installation procedure. |
||
6 |
Click the Enroll Now button to open a new window for authenticating the connector to the Webex cloud.
|
||
7 |
If you are not already signed in to Control Hub, sign in using a Webex administrator account. |
||
8 |
Check the Allow Access to the Gateway Management Connector check box. You get an Enrollment successful screen. ![]() |
Connector states of both management and telemetry connectors are displayed on the connector details page at https://{connector IP address}.
The following table describes the management connector states and statuses:
Management connector states |
Connectivity Status |
Description |
---|---|---|
Running |
Connected |
Indicates that the connector is in the running state and the device is connected to the Cisco Webex cloud. |
Running |
Not Connected |
Indicates that the connector is in the running state, but the device is not connected to the Cisco Webex cloud. |
Running |
Heartbeat Failed |
Indicates that the connector is in the running state, but heartbeat failed for the enrolled device. |
Running |
Enrollment Failed |
Indicates that the connector is in the running state, but enrollment of the device to the Cisco Webex cloud failed. |
The following table describes the telemetry connector states and statuses:
Telemetry Connector States |
Connectivity Status |
Description |
---|---|---|
Not Installed |
Not Available |
Indicates that the telemetry connector is not installed. |
Downloading |
Not Available |
Indicates that the telemetry connector download is in progress. |
Installing |
Not Available |
Indicates that the telemetry connector installation is in progress. |
Not configured |
Not Available |
Indicates that the telemetry connector installation is successful, but services have not started or are configured yet. |
Running |
Not Available |
Indicates that the telemetry connector is running but information about its connectivity to the Cisco Webex cloud is not available. |
Running |
Connected |
Indicates that the telemetry connector is in the running state and it is connected to the Cisco Webex cloud. |
Running |
Not Connected |
Indicates that the telemetry connector is in the running state but it is not connected to the Cisco Webex cloud. |
Running |
Heartbeat Failed |
Indicates that the telemetry connector is in the running state and the telemetry heartbeat to the Cisco Webex cloud failed. |
Disabled |
Not Available |
Indicates that the telemetry connector is in the maintenance mode (disabled state) and information about its connectivity to the cloud is not available. |
Stopped |
Disconnected |
Indicates that the telemetry connector is in the stopped state (may be partial or both telemetry service and web-socket broker service are stopped) and it is not connected to the Cisco Webex cloud. |
This section describes alarms that are generated in the telemetry connector module. The Telemetry Connector alarms are sent to the Cisco Webex cloud and displayed in ControHub.
The following table describes the connector-related messages:
Title |
Description |
Severity |
Solution |
---|---|---|---|
Telemetry module started. |
This message is sent when the Telemetry module becomes functional. |
Alert |
NA |
Telemetry module upgraded. |
This message is sent when the Telemetry module has been upgraded from "old_version" to "new_version". |
Alert |
NA |
NETCONF connection failure. |
This alarm is raised when the Telemetry module fails to establish NETCONF connection to the gateway. |
Critical |
Verify that NETCONF is enabled on the gateway and that it is reachable from the connector. Try to disable and enable the connector container. If the problem persists, navigate to https://help.webex.com/contact, click Support, and raise a case. |
NETCONF authentication failure. |
This alarm is raised when the Telemetry module fails to establish NETCONF connection to the gateway. |
Critical |
Verify that username and password are configured correctly on the gateway. Try to disable and enable the connector container. If the problem persists, navigate to https://help.webex.com/contact, click Support, and raise a case. |
NETCONF SNMP events subscription failure. |
This alarm is raised when the Telemetry module fails to create a NETCONF subscription for SNMP events. |
Critical |
Verify that NETCONF is enabled on the gateway and that it is reachable in the connector. Try to disable and enable the connector container. If the problem persists, navigate to https://help.webex.com/contact, click Support, and raise a case. For more information on how to enable and disable, see Post-installation activities. |
Telemetry metrics collection failure. |
This alarm is raised when the Telemetry module fails to collect metrics from the gateway through a NETCONF GET query. |
Critical |
Verify that NETCONF is enabled on the gateway and that it is reachable from the connector. Try to disable and enable the connector container. If the problem persists, navigate to https://help.webex.com/contact, click Support, and raise a case. For more information on how to enable and disable, see Post-installation activities. |
Telemetry gateway connection failure. |
This alarm is raised when the connector fails to establish a web socket connection with the telemetry gateway. |
Critical |
Verify that the telemetry gateway URL (*.ucmgmt.cisco.com) is in the allowed list of the enterprise firewall and reachable from the gateway. If the problem persists, navigate to https://help.webex.com/contact, click Support, and raise a case. |
Failure of telemetry gateway connection through proxy. |
This alarm is raised when the connector fails to establish a connection to the configured proxy. |
Critical |
Verify that proxy details (IP address and port credentials) are configured correctly on the connector and that the proxy is reachable. If the problem persists, navigate to https://help.webex.com/contact, click Support, and raise a case. |
Local Administration of the Management Connector
After successful installation of the connector, your gateway will be ready to use with Webex Calling. If required, you can update a number of connector settings using the options available in the script menu:
You can relaunch the script at any time using the following command: tclsh bootflash:/gateway_connector/gateway_onboarding.tcl.
|
===============================================================
Webex Managed Gateway Connector
===============================================================
Options
s : Display Status Page
v : View and Modify Cloud Connector Settings
e : Enable Guestshell
d : Disable Guestshell
l : Collect Logs
r : Clear Logs
u : Uninstall Connector
q : Quit
===============================================================
Select an option from the menu:
Enable Guestshell
Enable the cloud connector using the e: Enable Guestshell
menu option. This changes the status of the connector from INACTIVE
to ACTIVE
.
Disable Guestshell
Disable the cloud connector using the d: Disable Guestshell
menu option. This changes the status of the connector from ACTIVE
to INACTIVE
.
Uninstall Connector
Uninstall the cloud connector using the u: Uninstall Connector
menu option. This deletes all the data in the Guestshell container and removes all configurations that are related to the
cloud connector.
Collect Logs
Collect the logs using the l: Collect Logs
menu option. The system displays the location where these logs are stored after collecting the logs.
If you have an active support case with Cisco TAC, you can attach the logs directly to your service request using the command copy bootflash:/guest-share/<log-filename> scp://<case-number>:<cxd-token>@cxd.cisco.com . |
The following is a sample command:
vcubeprod#copy bootflash:/guest-share/gateway_webex_cloud_logs_2022114090628.tar.gz scp://123456789:a1b2c3d4e5@cxd.cisco.com
Clear Logs
Clear all log files in the device using the r: Clear Logs
menu option. This deletes all existing logs except the latest logs of the Tcl script and connectors.
View and Modify Cloud Connector Settings
Make the following changes to the existing settings of a cloud connector using the v: View and Modify Cloud Connector Settings
menu option.
===============================================================
Webex Managed Gateway Connector
===============================================================
Script Version : 2.0.2
Hostname/IP Addr : 10.65.125.188
DNS Server(s) : 10.64.86.70
Gateway Username : lab
External Interface : GigabitEthernet1
Proxy Hostname/IP Addr : proxy-wsa.esl.cisco.com:80
===============================================================
Options
c : Update Gateway Credentials
e : Update External Interface
p : Update Proxy Details
n : Update DNS Server
k : Update Connector Package Verification Key
l : Modify log level for Cloud Connector
h : Go to home menu
q : Quit
===============================================================
Select an option from the menu: c
Update Gateway Credentials
Update the gateway username and password using the c: Update Gateway Credentials
menu option.
Update External Interface
Change the interface to which the connector is bound and the connector IP address using the v: View and Modify Cloud Connector Settings
menu option.
Update Proxy Details
You can perform the following tasks using the p: Update Proxy Details
menu option:
-
i: Update Proxy IP and Port
-
c: Update Proxy Credentials
-
r: Remove Proxy Credentials
-
a: Remove All Proxy Details
-
h: Go to home menu
Update Connector Package Verification Key
If you have a technical issue and are asked by the support engineer to replace your package verification key, upload the new
gateway-webex-connectors.gpg file to bootflash:/gateway_connector/ and use the k: Update Connector Package Verification Key
menu option to verify.
Modify Log Level for the Management Connector
Change the logging level for the connector using the l: Modify log level for Cloud Connector
menu option and then selec one of the following options:
===============================================
Number Log Level
===============================================
1 DEBUG
2 INFO
3 WARNING
4 ERROR
5 CRITICAL
===============================================
To manage your gateway instance:
-
Under SERVICES, click Calling and then the Managed Gateways tab.
-
For the applicable gateway instance, click the adjacent dots (…) in the Actions column and select the applicable action.

Pause or resume connector
Pause Connector instructs the management connector to stop the telemetry connector. You can use this option to stop the telemetry connector temporarily while troubleshooting any issues with a gateway. When you pause the connector, services such as configuration validation doesn’t work. Use the Resume Connector action to restart the telemetry connector.
Click Pause Connector from the Actions menu to pause your management connector.

To resume the connector that you paused, click Resume Connector in the Actions menu.

Event history
Control Hub records and displays the event history for your managed gateways. You can view the details of an individual gateway or the consolidated details of all your managed gateways. Click Event History in the Calling page for the event details of all your managed gateways.

For event details specific to a gateway, click Event History in the Actions menu for that gateway.
Delete gateway
Click Delete Gateway in the Actions menu to delete any of your gateway instances. Click Confirm.

You can’t delete a gateway instance with assigned services. You must unassign the services first. |
After the gateway is enrolled, you can continue the configuraiton at Assign Services to Managed Gateways.