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.133 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.133 255.255.255.255 VirtualPortGroup0
!
 

The TCL script tracks and saves the configuration changes to the Cisco IOS XE startup configuration.

As part of the uninstallation process, the TCL script removes the configuration changes.

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).

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.1 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:

  1. Create a new directory using mkdir bootflash:/image.

  2. Expand the IOS binary image using: request platform software package expand file bootflash:/<image>.bin to bootflash:/image.

  3. In configuration mode, remove current boot options using: no boot system.

  4. Configure new boot statement: boot system bootflash:/image/packages.conf.

  5. Exit from configuration mode, save configuration, and reboot.

  6. Once the router has restarted, use show version to verify that the router booted from bootflash:/image/packages.conf. If yes:

    1. Verify that the bootflash:/sysboot directory is empty.

    2. Delete the remaining IOS binary image.

    3. Delete any core images using delete /f /r bootflash:/core/*.

    4. Delete tracelog files using delete /f /r bootflash:/tracelogs/*.

    5. 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
Complete the following steps in Control Hub to add a new gateway instance.

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.

Complete the following steps to install the gateway connector on the Cisco IOS XE GuestShell container.

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


  • This command downloads and runs a connector installation script. You can copy this string from the dialog that you see immediately after you choose to add a new gateway in Control Hub.

  • If it is not available already, the script downloads the connector package and stores it in the bootflash:/gateway_connector directory.

  • The script also carries out precondition checks for Cisco IOS XE version, available disk space in bootflash, and so on. The precondition check status must be "Passed" to proceed with the installation.

  • With some terminal applications, backspace may not work correctly and copy / paste functionality may be limited while running the script.

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.


 ===============================================================
             Webex Gateway Connector Installation
 ===============================================================


 Choose the external-interface from the below list of available interfaces:
 ===============================================================
   Number          Interface          IP-Address        Status
 ===============================================================
     1          GigabitEthernet1      10.65.125.142       up    
 ===============================================================

 Enter a number to choose the external interface: 1

 
  • The script creates a Virtual Port Group interface that shares the same IP as that of the chosen interface. It is used for the routing of GuestShell container traffic.

  • The script displays only the interfaces which are in "up" state and have IP addresses assigned.

2

Configure the DNS server to be used by the connector. By default the servers that are configured in IOS are used.

These DNS settings were detected in the gateway configuration:
 72.163.128.140 
Do you want to use these settings for the connector? [Y/n]: 

 

Y is the default input here. If you press "Enter", Y is taken as the input.


 
Detected settings may be overridden if necessary:
These DNS settings were detected in the gateway configuration:
72.163.128.140
Do you want to use these settings for the connector? [Y/n]: n
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.


These proxy settings were detected in the gateway configuration:
 Proxy Server : proxy-wsa.esl.cisco.com
 Proxy Port   : 80
Do you want to use these settings for the connector? [Y/n]: 
  • If you say 'n', the system asks if you require a proxy. Enter the proxy hostname/IP address, if you require one.

    These proxy settings were detected in the gateway configuration:
    Proxy Server : proxy-wsa.esl.cisco.com
    Proxy Port : 80
    Do you want to use these settings for the connector? [Y/n]:n
    Proxy required? [y/N]: y
    Enter proxy hostname/IP address:
    
  • Reenter the password if the proxy requires one.

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.


SNMP Traps for syslog messages are
configured at <alerts> level and they would be changed to <notifications>
level in order to push notifications to the Webex Cloud.
Please confirm if it is ok to proceed?:  [Y/n]: 
5

Enter the connector IP address.


 Enter Connector IP address: 10.65.125.227
6

Enter the username and password that the connector uses to access the router NETCONF interface.


Enter Gateway username: lab
Enter Gateway password: ***
Confirm Gateway password: ***

 

Type in the password manually. Copy and paste might not work.

Enter the gateway credentials that you identified in the Prerequisites section. The connector uses the credentials to access the router IOS NETCONF interface.

7

You get the "Cloud connector is installed successfully" message after the successful installation.


===============================================================
                 Webex Managed Gateway Connector
===============================================================

  *** Cloud connector is installed successfully. ***
-------------------------------------------------------
         *** Interface Status ***
-------------------------------------------------------
   Interface               IP-Address          Status
-------------------------------------------------------
   GigabitEthernet1        10.65.125.142       up    
   VirtualPortGroup0       10.65.125.142       up    
   Connector               10.65.125.188       up
   
-------------------------------------------------------

          *** App Status ***
-------------------------------------------------------
 Service                 Status
-------------------------------------------------------
 Guestshell              RUNNING
 Management Connector    RUNNING
-------------------------------------------------------

===============================================================
 Select option h for home menu or q to quit: 


 

You can quit the script by choosing the 'q' option after successful installation. If there is installation failure, you can choose 'h' option to change any settings, collect logs, and so on. Refer to the Post-installation Activities section for more details. If you want to retry installation, you can choose uninstallation and then relaunch the script to try installation again.


 

You can launch (or relaunch) the TCL script directly using bootflash:gateway_connector/gateway_onboarding.tcl or https://binaries.webex.com/ManagedGatewayScriptProdStable/gateway_onboarding.tcl at any given point.

What to do next

Go to the next procedure to complete the gateway enrollment process in Control Hub.
Complete the following steps in Control Hub to enroll your gateway.

Before you begin

The management connector must be installed on the gateway already.

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.


 
Make sure that the connector is successfully installed before you perform this step.

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.


 
  • Ensure that your browser is configured to allow popups for this page before you click Next.

  • Access the connector management page and complete the enrollment process within an hour.

    If it's not possible to complete the enrollment within an hour, restart the enrollment process from step 1 of this procedure. The gateway details that you entered earlier will not be saved.

    To continue this process from a different or restarted browser (within an hour), select the Enroll Gateway option for your gateway on the Control Hub Managed Gateways page.

  • The connector web server uses a self-signed certificate. On the browser, you must allow or accept the certificate.

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.


 
Ensure that your browser is configured to allow popups.

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:

Table 1. Management Connector States

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:

Table 2. Telemetry Connector States

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 telemetry cloud is not available.

Running

Connected

Indicates that the telemetry connector is in the running state and it is connected to the telemetry cloud.

Running

Not Connected

Indicates that the telemetry connector is in the running state but it is not connected to the telemetry 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 telemetry cloud.

This section describes alarms that are generated in the telemetry connector module. The Telemetry Connector alarms are sent to the telemetry 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:

  1. Under SERVICES, click Calling and then the Managed Gateways tab.

  2. 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.