Documentation>Cisco IoT Operations Dashboard
Cisco IoT Operations Dashboard

Device Configuration and Initiating Connection to OD

Configuring Devices Managed by CLI/Local Manager

IMPORTANT: When you manage an IE3x00 device, you are responsible for having the configuration needed for the DNS resolution of the IoT OD URL that is configured in the CLI. Use either the IP name server or the static IP host config. This feature will not work unless the DNS resolution works. Invoke the required CLI command for IoT OD Services configuration on the IE3x00 device.

  1. Prepare the Device.

    1. Equip the IE3x00 device with an SD card and set it up. Ensure the following:
      1. To work with IOx applications, the IE3x00 must have an SD card.
      2. Cisco ships every IE switch with IOS on the system flash. The SD card that is ordered as part of the shipment will be in FAT32 format.
      3. To enable Application Management for IoT OD services, the SD card should be formatted/re-partitioned to have an IOx partition. Once this is done, the IOx partition can be used for Application Management only.
      • Application-related data is stored on the IOx partition in the SD card.
      • Configuration and IOS images are stored on the system flash or the FAT32 partition in the SD card depending on the configuration.
      1. If the SD card is pre-formatted in FAT32 format, you can save configuration files and IOS image files on the SD card, but you cannot use IOx.
      2. If you format the SD card in ext4, you cannot use it to store configuration or IOS image files. The card will be entirely reserved for Application Management functions.
      3. If you partition the SD card to have an IOx partition along with the FAT32 partition, the FAT32 partition can be used for storing configuration or IOS image files, while the IOx partition can be used for Application Management.

        IMPORTANT: Before reformatting/partitioning the SD card, verify that all the necessary IOS image and configuration files from the SD card are copied to the eMMC (system flash) and other necessary files are backed up. Reformatting/partitioning the SD card wipes all information on the SD card

    2. Attach the required networking cables.
    3. Power up the device.

  2. Configure SD card and Enable IOx.

    1. Configure AppGigabitEthernet1/1 in trunk mode. Cisco recommends that you configure this trunk with a native VLAN that is not likely to be used anywhere in the switch. It is also possible, but not required, to allow on this trunk only the VLANs needed for communication from the applications and the internet or other VLANs. If using a native VLAN number greater than 1004 like the example below, make sure the switch is configured for "vtp mode transparent" to allow for the creation of this VLAN. With this configuration, applications will be deployed in any desired VLAN you wish the application traffic to follow. 
       vlan 4094
     name app-man-native-vlan
 interface AppGigabitEthernet1/1
     switchport trunk native vlan 4094
     switchport mode trunk
 
 Example:
 IE-3400#conf t
 Enter configuration commands, one per line.  End with CNTL/Z.
 IE-3400(config)#interface AppGigabitEthernet1/1
 IE-3400(config-if)#switchport mode trunk

    Note: Before formatting the SD card, backup or move to the boot flash any required files/data from the SD card. 2. Format/partition the SD card to create the required IOx partition in the card, if not already done. This action erases all data on the card and format/partitions the card.

         // The following command will allocate the complete SD card for use by IOx
     format sdflash: ext4
            
     Example:
     IE-3400#format sdflash: ext4
     Format operation may take a while. Continue? [confirm]
     Format operation will destroy all data in "sdflash:".  Continue? [confirm]
     Format operation reloads, if partitions are there. Continue? [confirm]
     format completed with no errors

    1. Enable IOx.

       iox
 
 Example:
 
 IE-3400#conf t
 Enter configuration commands, one per line.  End with CNTL/Z.
 IE-3400#iox
 Warning: Do not remove SD flash card when IOx is enabled or errors on SD device could occur.

    2. Verify that IOx is running correctly.

      show iox-service

Example 1 : IOx is up and running

IE-3400#show iox-service
IOx Infrastructure Summary:
---------------------------
IOx service (CAF)              : Running
IOx service (HA)               : Not Supported
IOx service (IOxman)           : Running
IOx service (Sec storage)      : Running
Libvirtd                       : Running
Dockerd                        : Running

Example 2 : IOx is not up

IE-3400#show iox-service
IOx Infrastructure Summary:
---------------------------
IOx service (CAF)              : Not Running
IOx service (HA)               : Not Supported
IOx service (IOxman)           : Not Running
IOx service (Sec storage)      : Not Running
Libvirtd                       : Running
Dockerd                        : Not Running

  3. Configure the IE3x00 Device to Connect to IoT OD.

    Execute a set of IOS commands on the device CLI to configure the device to connect to IoT OD.

    1. In order for the IoT OD to establish a connection with the device, it is essential to have a privileged user (privilege level 15) available on the device. If such a user does not exist, you can create a user on the device using the username command as shown in the example below:

       username odserviceuser privilege 15 algorithm-type scrypt secret

    2. Ensure that the device profile with the matching credentials exists in IoT OD and this device profile is assigned to the current device you are using in IoT OD. To verify this, do the following:

      1. Click on the device entry in the Devices > Staged to open the device Summary page.
      2. Click View More and compare the values of Device Profile, Admin Username and Admin Password fields (Click the "eye" icon to view the password value) to the expected values.

    3. Ensure that the minimum IOS XE version is 17.12.x.

    4. Configure the authentication-related settings and WSMA settings.

      IMPORTANT: Usage of the WSMA service relies on http, so both http server and http secure-server are required to be enabled in the configuration.
      Note: Please review running-config on the device first. Some related configurations might be available out of the box.

         aaa new-model
     aaa authentication login default local
     aaa authorization exec default local
     
     ip http server
     ip http authentication local
     ip http secure-server
     
     wsma agent exec
       profile exec
     
     wsma profile listener exec
       transport http path /wsma/exec
       
     cgna gzip
     
     archive
      path flash:/
      maximum 3

    IMPORTANT: The "ip http server" and "ip http secure-server" commands initiates a web server on the device, which can be accessed using port 443. If the device is exposed to the internet without enterprise firewall protection, it is important to control access to this web service to prevent potential security risks. For more details on this issue and resolution, see Technote: Troubleshooting tips. For any assistance, please contact: Cisco TAC

    1. Configure the cgna transport profile. The exact command to configure a transport profile will be different, based on the IOS-XE version running in the device.

      • Configuration for devices running version 17.12.1 and above:
      ida transport-profile wst
 callhome-url wss://:443/wst/cgna/+
 active
 
 // Example for the US Cluster:
 ida transport-profile wst
  callhome-url wss://us.ciscoiot.com:443/wst/cgna/IE-3300-8U2X+FCW2507P3V3
  active
 
 // Example for the EU Cluster:
 ida transport-profile wst
  callhome-url wss://eu.ciscoiot.com:443/wst/cgna/IE-3300-8U2X+FCW2507P3V3
  active

    2. Configure the cgna registration profile.

      cgna profile cg-nms-register
 transport-profile wst
 add-command show version | format flash:/managed/odm/cg-nms.odm
 add-command show inventory | format flash:/managed/odm/cg-nms.odm
 interval 3
 active
 url https://&ltIoTOD cluster FQDN>/cgna/ios/registration
 gzip

      Once the configuration is done, the device will connect to IoT OD and trigger the registration process.

    3. Enable DNS on the switch, if it is not already acquired through DHCP server.

      Note: This is important if the switch is configured with static IP and the static default gateway and not explicitly given a DNS server to use. In this example, we use a Cisco DNS. You can use any DNS server.

    To verify, execute the following commands: 

         IR1800_FCW2720Y0B5#ping us.ciscoiot.com
     Type escape sequence to abort.
     Sending 5, 100-byte ICMP Echos to 35.84.105.79, timeout is 2 seconds:
     .....
     Success rate is 0 percent (0/5)
     IR1800_FCW2720Y0B5#
    Ping will fail and that is expected, however it is important to validate that the hostname has been resolved to an ip address. The configured DNS server can be checked with "show ip dns view".

    If the DHCP server does not provide DNS, a DNS must be explicitly configured in the device. An example is as below: 

         ip name-server 208.67.222.222 208.67.220.220

Configuring Devices managed by DNAC

Steps for configuring an IE3x00 device managed by DNAC are very similar to those outlined above for a CLI-managed device. Enter the CLI required in the DNAC template and push it to the device from DNAC instead of entering it directly in the CLI. This section will focus on the differences from the CLI method.

  1. Prepare the device.

    1. Equip the IE3x00 device with an SD card and set it up.
    2. Attach the required networking cables.
    3. Power up the device.
    4. Create the DNAC template in preparation for managing the switch (or modify the existing template accordingly).

  2. Configure and enable IOx.

    1. The configuration CLI needed for the interface towards IOx is the same as outlined above for a CLI-managed switch. Add that config to the DNAC template.
    2. Enable IOx, if not done manually, then use the method outlined in Step 4 below (small applet script) within a DNAC template.
    3. Format SD card on the IE3x00 and enable IOx on the switch.
    4. Use this small applet script in the DNAC template to handle responses from the CLI when the SD card is formatted, and IOx is enabled. 
        #MODE_ENABLE
  #INTERACTIVE
  format sdflash: ext4ContinueContinueContinue
  terminal shell
  sleep 15
  terminal no shell
  #ENDS_INTERACTIVE
  #MODE_END_ENABLE
  iox

  3. Configure the device to connect to IoT OD. The configuration required here is identical to the configuration using CLI, with the following exception:

    1. Follow the CLI configuration procedure in step 7 under Configure the IE3x00 Device to Connect to IoT OD.
    2. Specify http authentication: "ip http authentication local".

    DNAC creates a "aaa group" and relies on external authentication. However, we want to rely on local authentication for the "odserviceuser". Add the code below in the DNAC template. This code relies on a "aaa group" for http authentication and authorization. In addition to using the DNAC-created groups, it inserts local as a first option, allowing OD to use local authentication. This configuration will not conflict with DNAC and will still allow the user to use external "aaa" users to connect and authenticate to the WebUI of the switch, should they choose.

     aaa authentication login od_authen local group radius group dnac-network-radius-group
 aaa authorization exec od_author local group radius group dnac-network-radius-group
 
 ip http authentication aaa login-authentication od_authen
 ip http authentication aaa exec-authorization od_author

Verifying the Configuration

Ensure that the configuration steps are complete and the template from CLI / DNAC is pushed to the switch. Now you can verify using the following commands if the device is configured correctly to connect to IoT OD.

  • Show ida transport-profile name wst (17.12.1 and above) 
      // Verify that IDA status is connected
  // Notice the line "IDA Status: Connected" in the show command out below.
  
  Example:
  #show ida transport-profile name wst
  Profile Name: wst
  Activated at: Fri Sep 29 00:00:43 2023
  Reconnect Interval: 30 seconds
  keepalive timer Interval: 50 seconds
  Source interface: [not configured]
  callhome-url: wss://us.ciscoiot.com:443/wst/cgna/IE-3300-8U2X+FCW2507P3V3
  Local TrustPoint: CISCO_IDEVID_SUDI
  Remote TrustPoint: [not configured]
  Execution-url: http://localhost:80
  Proxy-Addr: [not configured]
  IDA Status: Connected
  State: Wait for activation
  Last successful response at Fri Sep 29 00:00:56 2023
  Last failed response not found
  Last failed reason: not found
  • Show cgna profile name cg-nms-register 
     // Verify that the profile has "State: Profile disabled"
 // That is the expected state after successful registration

 Example:
 #show cgna profile name cg-nms-register
 Profile Name: cg-nms-register
 Deactivated at: Fri Mar 17 03:14:45 2023
 URL: https://us.ciscoiot.com/cgna/ios/registration
 Transport-profile: wst
 Payload content type: xml
 Interval: 3 minute
 Transfer count: 1
 gzip: activated
 Profile command:
     show version | format flash:/managed/odm/cg-nms.odm
     show inventory | format flash:/managed/odm/cg-nms.odm
 State: Profile disabled
 Timer stopped at Fri Mar 17 03:14:46 2023
 Last successful response not found
 Last failed response not found

Verifying the Device Status in the IoT OD

If IoT OD didn't receive any registration attempt, the IE3x00 device will stay in the Devices > Staged list. Check the following on the device:

  • Verify that the device has connectivity to the appropriate IoT OD cluster (US/EU) by using the telnet command.

      // Verify that opening a telnet session to the cluster is successful. The output should have "Open"
  
  Example:
  #telnet us.ciscoiot.com 443
  Trying us.ciscoiot.com (10.105.58.227, 443)... Open

  • Once a device connects with a registration request, the device configuration is recognized and validated by IoT OD, and the device automatically moves from Devices > Staged status to Registered status in your IoT OD Organization.

    1. The IE3x00 device will move to Devices > Registered with an Up status indicator when the device registration process is completed successfully. You will see the following sequence of events in the event log for such cases.

    Device Config

    Device Config

    1. If IoT OD received a registration attempt but had some issues, (e.g., incorrect credentials), the IE3x00 device will move to Devices > Registered with Config Failure status.

  • If you encounter problems, use the Event Log page on the device level to see the connectivity and Application Manager-related events. Use troubleshooting tools on the device Troubleshooting page for debugging.

    Note: The Troubleshooting page allows Ping IP, Traceroute IP, and IOS Show Commands execution on the device. * To use Troubleshooting tools, the device should register successfully on IoT OD and establish websocket tunnel.
    * The IOS Show Commands will work only if you apply a proper configuration for wsma on the IE3x00 device. * Refer to step 4 in Configure the IE3x00 Device to Connect to IoT OD section above. * It is critical to configure wsma listeners because wsma exec part might not be available by default on the IE3x00 device)

  • If the device moves from Staged to Registered, but the device status shows as Registering, and the Event Logs indicate timeout messages as shown below, the likely cause is a connectivity issue between the device and IoT OD.

    Device Config

  • If the credentials do not match, the event logs will show an authentication failure. If that occurs, run the user creation command again, using the correct username and password. To find the correct credentials, go to the Summary page, click on View More in the right corner, and a slider will appear with the username and password.

    Device Config

  • Once the IE3x00 device appears with the status Up in the Devices > Registered tab, click on the device name, and check the Applications tab on the device to verify that the Application Management is enabled successfully. In case of successful discovery, the details will appear similar to the image below.

    Device Config

  • In case the value of IOx status field is not up and the field Last Error on the device indicates any connectivity issue, try executing the Refresh IOx action. If the issue is still unresolved, check the error message and see the Application Management troubleshooting section for further debugging.

For more details on possible errors and corresponding solutions see Troubleshooting Tips.

Next