Contents

CNS Image Agent

Finding Feature Information

Your software release may not support all the features documented in this module. For the latest caveats and feature information, see Bug Search Tool and the release notes for your platform and software release. To find information about the features documented in this module, and to see a list of the releases in which each feature is supported, see the feature information table at the end of this module.

Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/​go/​cfn. An account on Cisco.com is not required.

Prerequisites for CNS Image Agent

  • Determine where to store the Cisco images on a file server to make the image available to many other networking devices. If the Cisco Networking Services Event Bus is to be used to store and distribute the images, the Cisco Networking Services event agent must be configured.
  • Set up a file server to enable the networking devices to download the new images. Protocols such as TFTP, HTTP, HTTPS, and rcp can be used.
  • Determine how to handle error messages generated by Cisco Networking Services image agent operations. Error messages can be sent to the Cisco Networking Services Event Bus or an HTTP or HTTPS URL.

Restrictions for CNS Image Agent

During automated image loading operations you must try to prevent the Cisco device from losing connectivity with the file server that is providing the image. Image reloading is subject to memory issues and connection issues. Boot options must also be configured to allow the Cisco device to boot another image if the first image reload fails. For more details see the “Managing Configuration Files” module of the Cisco IOS Configuration Fundamentals Configuration Guide.

Information About CNS Image Agent

Cisco Networking Services Image Agent

Administrators maintaining large networks of Cisco devices need an automated mechanism to load image files onto large numbers of remote devices. Existing network management applications are useful to determine which images to run and how to manage images received from the Cisco online software center. Other image distribution solutions do not scale to cover thousands of devices and cannot distribute images to devices behind a firewall or using Network Address Translation (NAT). The Cisco Networking Services image agent enables the managed device to initiate a network connection and request an image download allowing devices using NAT, or behind firewalls, to access the image server.

The Cisco Networking Services image agent can be configured to use the Cisco Networking Services Event Bus. To use the Cisco Networking Services Event Bus, the Cisco Networking Services event agent must be enabled and connected to the Cisco Networking Services event gateway in the Cisco Networking Services Configuration Engine. The Cisco Networking Services image agent can also use an HTTP server that understands the Cisco Networking Services image agent protocol. Deployment of Cisco Networking Services image agent operations can use both the Cisco Networking Services Event Bus and an HTTP server.

How to Configure CNS Image Agent

Configuring the Cisco Networking Services Image Agent

Cisco Networking Services uses a unique identifier to identify an image agent associated with that Cisco device. Using the same process as Cisco Networking Services event and configuration agents, the configuration of the cns id command determines whether an IP address or MAC address of a specified interface, the hardware serial hardware number of the device, an arbitrary text string, or the hostname of the device is used as the image ID. By default, the system uses the hostname of the device.

The Cisco Networking Services image ID is sent in the content of the messages sent by the image agent and allows an application to know the unique image ID of the Cisco device that generated the message. A password can be configured and associated with the image ID in the image agent messages.

Before You Begin

Perform this task to configure Cisco Networking Services image agent parameters using CLI commands.

  • To configure the Cisco Networking Services image agent to use HTTP or HTTP over SSL (HTTPS) to communicate with an image server, you need to know the URL for the image server and the URL to which status messages can be sent.
  • If you are using HTTPS to communicate with the image server, you must set up security certificates to allow the server to be authenticated by the image agent when the connection is established.
SUMMARY STEPS

    1.    enable

    2.    configure terminal

    3.    Do one of the following:

    • cns id type number {ipaddress| mac-address} [event| image]
    • cns id {hardware-serial| hostname| string text} [event| image]

    4.    cns password password

    5.    cns image [server server-url[status status-url]]

    6.    cns image password image-password

    7.    cns image retry seconds

    8.    exit


DETAILED STEPS
     Command or ActionPurpose
    Step 1 enable


    Example:
    Device> enable
     

    Enables privileged EXEC mode.

    • Enter your password if prompted.
     
    Step 2 configure terminal


    Example:
    Device# configure terminal
     

    Enters global configuration mode.

     
    Step 3Do one of the following:
    • cns id type number {ipaddress| mac-address} [event| image]
    • cns id {hardware-serial| hostname| string text} [event| image]


    Example:
    Device(config)# cns id fastethernet 0/1 ipaddress image


    Example:
    Device(config)# cns id hardware-serial image
     

    Specifies a unique Cisco Networking Services ID and interface type and number from which to retrieve the unique ID.

    or

    Specifies a unique Cisco Networking Services ID assigned from the hardware serial number, device hostname, or an arbitrary text string.

    The following information applies to either version of the syntax.

    • Use the event keyword to specify an event agent ID.
    • Use the image keyword to specify an image agent ID.
    • If no keywords are used, the configuration agent ID is configured.
     
    Step 4 cns password password


    Example:
    Device(config)# cns password password1
     

    Specifies a password for the Cisco Networking Services ID.

    You must configure the Cisco Networking Services password the first time a device is deployed, and the Cisco Networking Services password must be the same as the bootstrap password set on the Configuration Engine (CE).

     
    Step 5 cns image [server server-url[status status-url]]


    Example:
    Device(config)# cns image server https://10.21.2.3/cns/imgsvr status https://10.21.2.3/cns/status/
     

    Enables Cisco Networking Services image agent services and specifies the URL of the image distribution server.

    • Use the optional status keyword and status-url argument to specify the URL of a web server to which error messages are written.
    • If the status keyword and status-url argument are not specified, status messages are sent as events on the Cisco Networking Services Event Bus. To view the status messages on the Cisco Networking Services Event Bus, the Cisco Networking Services event agent must be configured.
     
    Step 6 cns image password image-password


    Example:
    Device(config)# cns image password abctext
     

    (Optional) Specifies a password for Cisco Networking Services image agent services.

    • If a password is configured, the password is included with the image ID in Cisco Networking Services image agent messages sent out by the image agent. The receiver of these messages can use this information to authenticate the sending device.
     
    Step 7 cns image retry seconds


    Example:
    Device(config)# cns image retry 240
     

    (Optional) Specifies an image upgrade retry interval in seconds.

    • The default interval is 60 seconds.
     
    Step 8 exit


    Example:
    Device(config)# exit
     

    Exits global configuration mode and returns the device to privileged EXEC mode.

    What to Do Next

    Proceed to the section to connect to the web server and download an image.

    If any of the commands in the task fail, proceed to the section to try to determine the problem.

     

    Retrieving a Cisco Networking Services Image from a Server

    Perform this task to poll the image distribution server using HTTP or HTTPS.


    Note
    Troubleshooting Tips
    • If the web server appears to be down, use the ping command to check connectivity.
    • If using HTTP, use the show ip http client all command to display information about HTTP clients and connections.
    Before You Begin

    This task assumes that you have already configured the Cisco Networking Services image agent using the tasks in the section.

    SUMMARY STEPS

      1.    enable

      2.    configure terminal

      3.    cns image retrieve [server server-url[status status-url]]


    DETAILED STEPS
       Command or ActionPurpose
      Step 1 enable


      Example:
      Device> enable
       

      Enables privileged EXEC mode.

      • Enter your password if prompted.
       
      Step 2 configure terminal


      Example:
      Device# configure terminal
       

      Enters global configuration mode.

       
      Step 3 cns image retrieve [server server-url[status status-url]]


      Example:
      Device(config)# cns image retrieve server https://10.19.2.3/imgsvr/ status https://10.19.2.3/imgsvr/status/
       

      Contacts a Cisco Cisco Networking Services image distribution server and downloads a new image if a new image exists.

      • Use the optional status keyword and status-url argument to specify the URL of a web server to which status messages are written.
      • If the server and status keywords are not specified, the server and status URLs configured with the cns image command are used.
      Note   

      We recommend using the cns trusted-server command to specify the host part of the server or status URL as a trusted server.

       

      Configuration Examples for CNS Image Agent

      Example: Enabling and Configuring Cisco Networking Services Agents

      The following example shows various Cisco Networking Services agents being enabled and configured starting with the configuration agent being enabled with the cns config partial command to configure an incremental (partial) configuration on a remote device. The Cisco Networking Services configuration engine IP address is 172.28.129.22, and the port number is 80. The Cisco Networking Services exec agent is enabled with an IP address of 172.28.129.23, and the Cisco Networking Services event agent is enabled with an IP address of 172.28.129.24. Until the Cisco Networking Services event agent is enabled, no other Cisco Networking Services agents are operational. 

       cns config partial 172.28.129.22 80
 cns exec 172.28.129.23 source 172.22.2.2
 cns event 172.28.129.24 source 172.22.2.1
 exit

      In the following example, the Cisco Networking Services image agent parameters are configured using the CLI. An image ID is specified to use the IP address of the GigabitEthernet interface 0/1/1, a password is configured for the Cisco Networking Services image agent services, the Cisco Networking Services image upgrade retry interval is set to four minutes, and image management and status servers are configured. 

      cns id GigabitEthernet0/1/1 ipaddress image
cns image retry 240
cns image password abctext
cns image server https://10.21.2.3/cns/imgsvr status https://10.21.2.3/cns/status/

      In the following example, the Cisco Networking Services image agent is configured to use the Cisco Networking Services Event Bus. An image ID is specified as the hardware serial number of the networking device, the Cisco Networking Services event agent is enabled with a number of parameters, and the Cisco Networking Services image agent is enabled without any keywords or options. The Cisco Networking Services image agent will listen for events on the Cisco Networking Services Event Bus. 

      cns id hardware-serial image
cns event 10.21.9.7 11011 keepalive 240 120 failover-time 5
cns image
cns image password abctext

      Example: Retrieving a Cisco Networking Services Image from a Server

      In the following example, the Cisco Networking Services image agent polls a file server using the cns image retrieve command. Assuming that the Cisco Networking Services image agent is already enabled, the file server and status server paths specified here will overwrite any existing image agent server and status configuration. The new file server will be polled and a new image, if it exists, will be downloaded to the networking device. 

       cns image retrieve server https://10.19.2.3/cns/ status https://10.19.2.3/cnsstatus/

      Additional References

      Related Documents

      Related Topic

      Document Title

      Cisco IOS commands

      Cisco IOS Master Commands List, All Releases

      Cisco Networking Services commands: complete command syntax, command mode, command history, defaults, usage guidelines, and examples.

      Cisco IOS Cisco Networking Services Command Reference

      Cisco Networking Services Configuration Engine

      Cisco CNS Configuration Engine Administrator Guide, 1.3

      Standards and RFCs

      Standard/RFC

      Title

      No new or modified standards/RFCs are supported by this feature, and support for existing standards/RFCs has not been modified by this feature.

      --

      MIBs

      MIB

      MIBs Link

      No new or modified MIBs are supported by this feature, and support for existing MIBs has not been modified by this feature.

      To locate and download MIBs for selected platforms, Cisco software releases, and feature sets, use Cisco MIB Locator found at the following URL:

      http:/​/​www.cisco.com/​go/​mibs

      Technical Assistance

      Description

      Link

      The Cisco Support and Documentation website provides online resources to download documentation, software, and tools. Use these resources to install and configure the software and to troubleshoot and resolve technical issues with Cisco products and technologies. Access to most tools on the Cisco Support and Documentation website requires a Cisco.com user ID and password.

      http:/​/​www.cisco.com/​cisco/​web/​support/​index.html

      Feature Information for CNS Image Agent

      The following table provides release information about the feature or features described in this module. This table lists only the software release that introduced support for a given feature in a given software release train. Unless noted otherwise, subsequent releases of that software release train also support that feature.

      Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/​go/​cfn. An account on Cisco.com is not required.

      Table 1 Feature Information for Cisco Networking Services Image Agent

      Feature Name

      Releases

      Feature Information

      Cisco Networking Services Image Agent

      12.2(33)SEE

      12.3(1)

      12.2(31)SB2

      12.2(33)SRB

      12.2(33)SB

      12.2(33)SXI

      The Cisco Networking Services Image Agent feature is an infrastructure in Cisco IOS software to enable automated installation and activation of Cisco IOS images on Cisco IOS networking devices.

      The following commands were introduced or modified by this feature: clear cns image connections, clear cns image status, cns id, cns image, cns image password, cns image retrieve, cns image retry, debug cns image, show cns image connections, show cns image inventory, show cns image status.

      CNS Image Agent

      CNS Image Agent

      Finding Feature Information

      Your software release may not support all the features documented in this module. For the latest caveats and feature information, see Bug Search Tool and the release notes for your platform and software release. To find information about the features documented in this module, and to see a list of the releases in which each feature is supported, see the feature information table at the end of this module.

      Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/​go/​cfn. An account on Cisco.com is not required.

      Prerequisites for CNS Image Agent

      • Determine where to store the Cisco images on a file server to make the image available to many other networking devices. If the Cisco Networking Services Event Bus is to be used to store and distribute the images, the Cisco Networking Services event agent must be configured.
      • Set up a file server to enable the networking devices to download the new images. Protocols such as TFTP, HTTP, HTTPS, and rcp can be used.
      • Determine how to handle error messages generated by Cisco Networking Services image agent operations. Error messages can be sent to the Cisco Networking Services Event Bus or an HTTP or HTTPS URL.

      Restrictions for CNS Image Agent

      During automated image loading operations you must try to prevent the Cisco device from losing connectivity with the file server that is providing the image. Image reloading is subject to memory issues and connection issues. Boot options must also be configured to allow the Cisco device to boot another image if the first image reload fails. For more details see the “Managing Configuration Files” module of the Cisco IOS Configuration Fundamentals Configuration Guide.

      Information About CNS Image Agent

      Cisco Networking Services Image Agent

      Administrators maintaining large networks of Cisco devices need an automated mechanism to load image files onto large numbers of remote devices. Existing network management applications are useful to determine which images to run and how to manage images received from the Cisco online software center. Other image distribution solutions do not scale to cover thousands of devices and cannot distribute images to devices behind a firewall or using Network Address Translation (NAT). The Cisco Networking Services image agent enables the managed device to initiate a network connection and request an image download allowing devices using NAT, or behind firewalls, to access the image server.

      The Cisco Networking Services image agent can be configured to use the Cisco Networking Services Event Bus. To use the Cisco Networking Services Event Bus, the Cisco Networking Services event agent must be enabled and connected to the Cisco Networking Services event gateway in the Cisco Networking Services Configuration Engine. The Cisco Networking Services image agent can also use an HTTP server that understands the Cisco Networking Services image agent protocol. Deployment of Cisco Networking Services image agent operations can use both the Cisco Networking Services Event Bus and an HTTP server.

      How to Configure CNS Image Agent

      Configuring the Cisco Networking Services Image Agent

      Cisco Networking Services uses a unique identifier to identify an image agent associated with that Cisco device. Using the same process as Cisco Networking Services event and configuration agents, the configuration of the cns id command determines whether an IP address or MAC address of a specified interface, the hardware serial hardware number of the device, an arbitrary text string, or the hostname of the device is used as the image ID. By default, the system uses the hostname of the device.

      The Cisco Networking Services image ID is sent in the content of the messages sent by the image agent and allows an application to know the unique image ID of the Cisco device that generated the message. A password can be configured and associated with the image ID in the image agent messages.

      Before You Begin

      Perform this task to configure Cisco Networking Services image agent parameters using CLI commands.

      • To configure the Cisco Networking Services image agent to use HTTP or HTTP over SSL (HTTPS) to communicate with an image server, you need to know the URL for the image server and the URL to which status messages can be sent.
      • If you are using HTTPS to communicate with the image server, you must set up security certificates to allow the server to be authenticated by the image agent when the connection is established.
      SUMMARY STEPS

        1.    enable

        2.    configure terminal

        3.    Do one of the following:

        • cns id type number {ipaddress| mac-address} [event| image]
        • cns id {hardware-serial| hostname| string text} [event| image]

        4.    cns password password

        5.    cns image [server server-url[status status-url]]

        6.    cns image password image-password

        7.    cns image retry seconds

        8.    exit


      DETAILED STEPS
         Command or ActionPurpose
        Step 1 enable


        Example:
        Device> enable
         

        Enables privileged EXEC mode.

        • Enter your password if prompted.
         
        Step 2 configure terminal


        Example:
        Device# configure terminal
         

        Enters global configuration mode.

         
        Step 3Do one of the following:
        • cns id type number {ipaddress| mac-address} [event| image]
        • cns id {hardware-serial| hostname| string text} [event| image]


        Example:
        Device(config)# cns id fastethernet 0/1 ipaddress image


        Example:
        Device(config)# cns id hardware-serial image
         

        Specifies a unique Cisco Networking Services ID and interface type and number from which to retrieve the unique ID.

        or

        Specifies a unique Cisco Networking Services ID assigned from the hardware serial number, device hostname, or an arbitrary text string.

        The following information applies to either version of the syntax.

        • Use the event keyword to specify an event agent ID.
        • Use the image keyword to specify an image agent ID.
        • If no keywords are used, the configuration agent ID is configured.
         
        Step 4 cns password password


        Example:
        Device(config)# cns password password1
         

        Specifies a password for the Cisco Networking Services ID.

        You must configure the Cisco Networking Services password the first time a device is deployed, and the Cisco Networking Services password must be the same as the bootstrap password set on the Configuration Engine (CE).

         
        Step 5 cns image [server server-url[status status-url]]


        Example:
        Device(config)# cns image server https://10.21.2.3/cns/imgsvr status https://10.21.2.3/cns/status/
         

        Enables Cisco Networking Services image agent services and specifies the URL of the image distribution server.

        • Use the optional status keyword and status-url argument to specify the URL of a web server to which error messages are written.
        • If the status keyword and status-url argument are not specified, status messages are sent as events on the Cisco Networking Services Event Bus. To view the status messages on the Cisco Networking Services Event Bus, the Cisco Networking Services event agent must be configured.
         
        Step 6 cns image password image-password


        Example:
        Device(config)# cns image password abctext
         

        (Optional) Specifies a password for Cisco Networking Services image agent services.

        • If a password is configured, the password is included with the image ID in Cisco Networking Services image agent messages sent out by the image agent. The receiver of these messages can use this information to authenticate the sending device.
         
        Step 7 cns image retry seconds


        Example:
        Device(config)# cns image retry 240
         

        (Optional) Specifies an image upgrade retry interval in seconds.

        • The default interval is 60 seconds.
         
        Step 8 exit


        Example:
        Device(config)# exit
         

        Exits global configuration mode and returns the device to privileged EXEC mode.

        What to Do Next

        Proceed to the section to connect to the web server and download an image.

        If any of the commands in the task fail, proceed to the section to try to determine the problem.

         

        Retrieving a Cisco Networking Services Image from a Server

        Perform this task to poll the image distribution server using HTTP or HTTPS.


        Note
        Troubleshooting Tips
        • If the web server appears to be down, use the ping command to check connectivity.
        • If using HTTP, use the show ip http client all command to display information about HTTP clients and connections.
        Before You Begin

        This task assumes that you have already configured the Cisco Networking Services image agent using the tasks in the section.

        SUMMARY STEPS

          1.    enable

          2.    configure terminal

          3.    cns image retrieve [server server-url[status status-url]]


        DETAILED STEPS
           Command or ActionPurpose
          Step 1 enable


          Example:
          Device> enable
           

          Enables privileged EXEC mode.

          • Enter your password if prompted.
           
          Step 2 configure terminal


          Example:
          Device# configure terminal
           

          Enters global configuration mode.

           
          Step 3 cns image retrieve [server server-url[status status-url]]


          Example:
          Device(config)# cns image retrieve server https://10.19.2.3/imgsvr/ status https://10.19.2.3/imgsvr/status/
           

          Contacts a Cisco Cisco Networking Services image distribution server and downloads a new image if a new image exists.

          • Use the optional status keyword and status-url argument to specify the URL of a web server to which status messages are written.
          • If the server and status keywords are not specified, the server and status URLs configured with the cns image command are used.
          Note   

          We recommend using the cns trusted-server command to specify the host part of the server or status URL as a trusted server.

           

          Configuration Examples for CNS Image Agent

          Example: Enabling and Configuring Cisco Networking Services Agents

          The following example shows various Cisco Networking Services agents being enabled and configured starting with the configuration agent being enabled with the cns config partial command to configure an incremental (partial) configuration on a remote device. The Cisco Networking Services configuration engine IP address is 172.28.129.22, and the port number is 80. The Cisco Networking Services exec agent is enabled with an IP address of 172.28.129.23, and the Cisco Networking Services event agent is enabled with an IP address of 172.28.129.24. Until the Cisco Networking Services event agent is enabled, no other Cisco Networking Services agents are operational. 

           cns config partial 172.28.129.22 80
 cns exec 172.28.129.23 source 172.22.2.2
 cns event 172.28.129.24 source 172.22.2.1
 exit

          In the following example, the Cisco Networking Services image agent parameters are configured using the CLI. An image ID is specified to use the IP address of the GigabitEthernet interface 0/1/1, a password is configured for the Cisco Networking Services image agent services, the Cisco Networking Services image upgrade retry interval is set to four minutes, and image management and status servers are configured. 

          cns id GigabitEthernet0/1/1 ipaddress image
cns image retry 240
cns image password abctext
cns image server https://10.21.2.3/cns/imgsvr status https://10.21.2.3/cns/status/

          In the following example, the Cisco Networking Services image agent is configured to use the Cisco Networking Services Event Bus. An image ID is specified as the hardware serial number of the networking device, the Cisco Networking Services event agent is enabled with a number of parameters, and the Cisco Networking Services image agent is enabled without any keywords or options. The Cisco Networking Services image agent will listen for events on the Cisco Networking Services Event Bus. 

          cns id hardware-serial image
cns event 10.21.9.7 11011 keepalive 240 120 failover-time 5
cns image
cns image password abctext

          Example: Retrieving a Cisco Networking Services Image from a Server

          In the following example, the Cisco Networking Services image agent polls a file server using the cns image retrieve command. Assuming that the Cisco Networking Services image agent is already enabled, the file server and status server paths specified here will overwrite any existing image agent server and status configuration. The new file server will be polled and a new image, if it exists, will be downloaded to the networking device. 

           cns image retrieve server https://10.19.2.3/cns/ status https://10.19.2.3/cnsstatus/

          Additional References

          Related Documents

          Related Topic

          Document Title

          Cisco IOS commands

          Cisco IOS Master Commands List, All Releases

          Cisco Networking Services commands: complete command syntax, command mode, command history, defaults, usage guidelines, and examples.

          Cisco IOS Cisco Networking Services Command Reference

          Cisco Networking Services Configuration Engine

          Cisco CNS Configuration Engine Administrator Guide, 1.3

          Standards and RFCs

          Standard/RFC

          Title

          No new or modified standards/RFCs are supported by this feature, and support for existing standards/RFCs has not been modified by this feature.

          --

          MIBs

          MIB

          MIBs Link

          No new or modified MIBs are supported by this feature, and support for existing MIBs has not been modified by this feature.

          To locate and download MIBs for selected platforms, Cisco software releases, and feature sets, use Cisco MIB Locator found at the following URL:

          http:/​/​www.cisco.com/​go/​mibs

          Technical Assistance

          Description

          Link

          The Cisco Support and Documentation website provides online resources to download documentation, software, and tools. Use these resources to install and configure the software and to troubleshoot and resolve technical issues with Cisco products and technologies. Access to most tools on the Cisco Support and Documentation website requires a Cisco.com user ID and password.

          http:/​/​www.cisco.com/​cisco/​web/​support/​index.html

          Feature Information for CNS Image Agent

          The following table provides release information about the feature or features described in this module. This table lists only the software release that introduced support for a given feature in a given software release train. Unless noted otherwise, subsequent releases of that software release train also support that feature.

          Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/​go/​cfn. An account on Cisco.com is not required.

          Table 1 Feature Information for Cisco Networking Services Image Agent

          Feature Name

          Releases

          Feature Information

          Cisco Networking Services Image Agent

          12.2(33)SEE

          12.3(1)

          12.2(31)SB2

          12.2(33)SRB

          12.2(33)SB

          12.2(33)SXI

          The Cisco Networking Services Image Agent feature is an infrastructure in Cisco IOS software to enable automated installation and activation of Cisco IOS images on Cisco IOS networking devices.

          The following commands were introduced or modified by this feature: clear cns image connections, clear cns image status, cns id, cns image, cns image password, cns image retrieve, cns image retry, debug cns image, show cns image connections, show cns image inventory, show cns image status.