Manage NCM firmware upgrade templates

Each firmware upgrade template defines a set of device-specific commands and options that NCM uses to upgrade the firmware on a device of that type. NCM provides a set of default firmware upgrade templates, and you can create new templates to enable firmware upgrades on other device types.

NCM default firmware upgrade templates

SolarWinds NCM provides firmware upgrade templates for the following device series:

• Cisco ASA 5512 Multi Context Mode

  Upgrades Cisco Adaptive Security Appliance (ASA) devices that have been partitioned into multiple contexts.

  To monitor a Cisco ASA device with multiple contexts, you must add each context as a node to be monitored by NCM. To do this, add the admin context by IP address. All other contexts are automatically discovered, and you can add each one as a node.

• Cisco ASA 5512 Single Context Mode

• Cisco Catalyst 2960

• Cisco Catalyst 3560

• Cisco Catalyst 3750

• Cisco Catalyst 3850

• Cisco IOS Software 2800/2801

• Cisco IOS Software 2921

• Cisco Nexus 5548

  This template performs an in-service software upgrade (ISSU) and then reboots the device. Rebooting the device ensures that the firmware upgrade is completed successfully. Use this template only for upgrades. The ISSU process does not support downgrades.

  If a Cisco Nexus device has multiple virtual device contexts (VDCs), firmware updates apply to all VDCs on the physical device. You cannot upgrade the firmware for an individual VDC.

• Cisco Nexus C7004 - ISSU

  This template performs an ISSU and then reboots the device. Rebooting the device ensures that the firmware upgrade is completed successfully. Use this template only for upgrades. The ISSU process does not support downgrades.

• Cisco Nexus C7004 - Traditional

  This template performs a traditional upgrade or downgrade. Use this template when ISSU is not supported.

• EtherWAN

• Juniper j2320 Junos

• Lenovo Campus NOS

• Lenovo RackSwitch CNOS version 10.7 and newer

• Lenovo RackSwitch CNOS versions before 10.7

Add a firmware upgrade template

1. Click Settings > All Settings.
2. Under Product Specific Settings, click NCM Settings.
3. In the Firmware Upgrade section, click Firmware Upgrade Templates.
4. Perform one of the following actions:
   • To create a template based on a predefined NCM template, select the template and click Edit. Then click Duplicate & Edit Firmware Upgrade Template.
   • To create a new template from scratch, click Add.
5. Enter a name and description.

6. In the Collect Info Commands section, specify the actions that NCM should perform to gather information from devices before they are upgraded with this template. To enable an action, select the check box and then enter the command to perform that action.

   For information about how NCM uses the information returned by these commands, see Collect Info commands.

   • Get current firmware image command (optional):

     1. In the command box, enter the command to retrieve the current firmware image path for the device.

        For example, the command for Cisco IOS devices is:

        show ver | include system image

     2. To identify what part of the returned value is the image path that NCM should capture, select Use capture results pattern. Then enter the string that the command returns with ${CaptureData} as a placeholder for the image path.

        For example, if the command returns System image file is "imagePath", enter:

        System image file is "${CaptureData}"

        For devices with multiple images (such as Cisco Nexus devices, which have a system image and a kickstart image), enter multiple patterns separated by the ${;} macro. For example:

        system image file is "${CaptureData}"${;}kickstart image file is:"${CaptureData}"

     

   • Get info on config register command (optional):

     1. In the command box, enter the command to retrieve the current configuration register value.

     2. To identify what part of the returned value is the configuration register value that NCM should capture, select Use capture results pattern. Then enter the string that the command returns with ${CaptureData} as a placeholder for the configuration register value.

     3. Enter the expected configuration register value in the Expected value field.

     • Different device models might require different config register values to allow the device to boot correctly after the upgrade. For example, the appropriate config register value for Cisco IOS is 0x2102. For Cisco ASA, it is 0x1.
     • This command is not applicable for Cisco Catalyst and Cisco Nexus devices.

     

   • Collect Boot Variable Info (required for Cisco ASA devices, not used for other devices)

     For Cisco ASA devices, enter the command to collect all existing boot paths.

     

   • Get free space command (optional)

     If you want NCM to verify that sufficient space is available to perform the upgrade operation, enter the command to check the amount of free space on the device.

     

   • Other commands (optional)

     Enter commands to collect any additional information to be displayed on the Upgrade Options panel during a firmware upgrade operation.

     

7. In the Upgrade Commands section, specify the firmware image type:

   • For devices with only one image:

     1. Enter any description (for example, "Main") in the Firmware Image Type box.
     2. Click Add New.

     

   • For devices that have multiple images, such as Cisco Nexus devices:

     1. Enter the first image type (for example, "System" or "Kickstart") in the Firmware Image Type box.
     2. Click Add New.
     3. Repeat to add other images.

     

8. (Optional) To associate this template with a specific firmware image, click Select New Image From Repository and then select the image.

   If you do not associate this template with a firmware image, users can select one later when they perform a firmware upgrade operation.

9. Enter the Upgrade firmware image command. See Upgrade firmware image command below for examples and information about the macros that can be used with this command.

   

10. Select the transfer protocol.

11. (Optional) To allow users to select additional actions to perform during the firmware upgrade operation, specify the actions in the Upgrade Commands section. To enable an action, select the check box and then enter the command to perform that action.

    See Upgrade Commands for more information about the commands and the macros available for use with each command. SolarWinds recommends always including the Update boot variable command.

12. In the Upgrade Options section, select the tasks to run before and after the upgrade with this template. These options are selected by default when a user performs an upgrade operation.

    If you select the Reboot device after upgrade option, the following setting is available: 

    Wait time between reboot and checking that the node is "Up"

    Use this setting to prevent errors for devices that have multiple up/down sequences after they reboot.

13. Click Save.

Collect Info commands

When a user performs a firmware upgrade operation with the template, NCM first runs the commands selected in the Collect Info section. These commands collect information from the devices, which the user can review before continuing with the upgrade.

Get current firmware image command

This command is optional. If it is included, NCM runs this command to determine which image the device currently uses. The capture results pattern enables NCM to capture the image path and file name from the command output.

NCM uses this information in the following ways:

• NCM automatically enters the image path and file name when the user selects the following Upgrade Options:

  • Backup existing firmware image
  • Delete existing firmware image

  

• NCM automatically enters the drive where the existing image is located in the Path to upload image field.

  

• If NCM determines that the device does not have enough free space to upload the new image, NCM uses this information to determine if deleting the existing image will free enough disk space to proceed.

If the template does not specify this command:

• To back up or delete the existing image, the user must manually specify the path on the Upgrade Options panel.
• If the device does not have enough free space, NCM will not be able to determine if deleting the existing image will free enough disk space to proceed.

Get info on config register

This command is optional. If it is included, NCM uses this information to determine if the configuration register needs to be updated. NCM retrieves the current configuration register value and compares it to the expected value. If the values do not match, NCM automatically selects the Update config register option on the Upgrade Options panel.

If the template does not specify this command, the Update Config Register option is deselected by default and users must manually select this option if necessary.

Collect Boot Variable Info

This command is required for Cisco ASA devices. It is not used for other devices. If this command is not specified for a Cisco ASA device, the firmware upgrade operation cannot be performed.

When a Cisco ASA device updates the boot variable (which tells the device what image it should boot from after a reboot), it must remove all existing boot paths. This command collects all existing boot paths and stores them in the ${BootItem} macro. This value is used by the Update boot variable command.

Get free space command

This command is optional. Include this command if you want NCM to check the amount of free space on the device. When you include this command:

• NCM displays the output of the "Get free space" command on the Upgrade Options page. This informs users of the amount of available space.
• NCM runs its own Free Space Detector over SNMP to verify that sufficient space is available to perform the operation.

The output of the "Get free space" command is not used to verify that sufficient space is available. However, including this command causes NPM to perform the SNMP free space verification.

Other commands

Other commands are optional. You can enter commands to collect additional information. This information is displayed on the Upgrade Options panel to help users determine whether to proceed with the firmware upgrade operation.

On a Cisco Nexus device, you cannot include pre-upgrade check commands that require the new image to already be uploaded on the device. For example, you cannot include commands to verify compatibility (show incompatibility) or to identify the upgrade impact (show install all impact).

Upgrade commands

Upgrade firmware image command

This command is required. This command copies the firmware image from the TFTP or SCP server to the device file system.

The following example is a command for non-Nexus Cisco devices. The ${SubFolder} macro enables simultaneous firmware upgrade operations.

copy ${TransferProtocol}://${StorageAddress}/${SubFolder}/${NewImageName} ${NewImageSlot}${CRLF}${CRLF}dir ${NewImageSlot} ${SuccessRegEx:${NewImageName}}

The following example is a command for Nexus Cisco devices. The ${SubFolder} macro enables simultaneous firmware upgrade operations. The ${System.FileName} macro specifies the type of image.

copy ${TransferProtocol}://${StorageAddress}/${SubFolder}/${System.FileName} ${NewImageSlot} vrf management${CRLF}${CRLF}${CRLF}${CRLF}dir ${NewImageSlot} ${SuccessRegEx:${System.FileName}}${CRLF}copy ${TransferProtocol}://${StorageAddress}/${SubFolder}/${Kickstart.FileName} ${NewImageSlot} vrf management${CRLF}${CRLF}${CRLF}${CRLF}dir ${NewImageSlot} ${SuccessRegEx:${Kickstart.FileName}}

The following macros can be used with this command.

Macro	Description
${TransferProtocol}	This macro resolves to the value selected for Transfer protocol. You can enter the value (TFTP or SCP) instead of this macro.
${StorageAddress}	(Applies only if you use TFTP to transfer the firmware image.) This macro resolves to the IP address specified in TFTP Server settings. You can enter the server IP address instead of this macro.
${SCPStorageAddress}	(Applies only if you use SCP to transfer the firmware image.) This macro resolves to the IP address specified in SCP Server settings. You can enter the server IP address instead of this macro.
${SCPServerUserName}	(Applies only if you use SCP to transfer the firmware image.) This macro resolves to the user name specified in SCP Server settings. You can enter the user name instead of this macro.
${SCPServerPassword}	(Applies only if you use SCP to transfer the firmware image.) This macro resolves to the password for the SCP user specified in SCP Server settings. You can enter the password instead of this macro.
${SubFolder}	This macro is required to enable firmware upgrade operations that use this template to run simultaneously with other firmware upgrade operations. The macro resolves to the name of a subfolder that is automatically created on the SCP or TFTP server. To enable multiple firmware operations to run simultaneously, NCM copies the files for each operation to a uniquely named subfolder instead of to the root directory. You must use this macro to specify a subfolder. Do not enter a subfolder name.
${NewImageName}	(Required for non-Nexus devices.) This macro resolves to the name of the firmware image that is selected in the Firmware image(s) field during an upgrade operation.
${System.FileName}	(Required for Nexus devices.) This macro resolves to the name of the system image that is selected in the Firmware image(s) field during an upgrade operation.
${KickStart.FileName}	(Required for Nexus devices.) This macro resolves to the name of the kickstart image that is selected in the Firmware image(s) field during an upgrade operation.
${NewImageSlot}	(Required for all devices.) This macro resolves to the value entered in the Path to upload image field during an upgrade operation (for example, flash: or disk0:).
${CRLF}	Use this macro to send the Enter command when a device asks confirmation questions. Also, when more than one command must be executed as part of an operation, use this macro to separate the commands.

Delete firmware image command

This command is optional. If it is included, users performing an upgrade operation can select the Delete existing firmware image option, which deletes the existing image. An example of this command is:

delete ${ExistingImagePath}${CRLF}${CRLF}${CRLF}

The following macros can be used with this command.

Macro	Description
${ExistingImagePath}	(Required for all devices.) This macro resolves to the value entered in the Image path field for the Delete existing firmware image option during an upgrade operation.
${CRLF}	Use this macro to send the Enter command when a device asks confirmation questions. Also, when more than one command must be executed as part of an operation, use this macro to separate the commands.

Back up firmware image command

This command is optional. If it is included, users performing an upgrade operation can select the Delete existing firmware image option, which backs up the existing image into NCM firmware upgrade storage. An example of this command is:

copy ${ExistingImagePath} ${TransferProtocol}://${StorageAddress}/${SubFolder}/ vrf management${CRLF}${CRLF}${CRLF}

The following macros can be used with this command.

Macro	Description
${ExistingImagePath}	(Required for all devices.) This macro resolves to the value entered in the Image path field for the Back up existing firmware image option during an upgrade operation.
${TransferProtocol}	This macro resolves to the value selected for Transfer protocol. You can enter the value (TFTP or SCP) instead of this macro.
${StorageAddress}	(Applies only if you use TFTP to transfer the firmware image.) This macro resolves to the IP address specified in TFTP Server settings. You can enter the server IP address instead of this macro.
${SCPStorageAddress}	(Applies only if you use SCP to transfer the firmware image.) This macro resolves to the IP address specified in SCP Server settings. You can enter the server IP address instead of this macro.
${SCPServerUserName}	(Applies only if you use SCP to transfer the firmware image.) This macro resolves to the user name specified in SCP Server settings. You can enter the user name instead of this macro.
${SCPServerPassword}	(Applies only if you use SCP to transfer the firmware image.) This macro resolves to the password for the SCP user specified in SCP Server settings. You can enter the password instead of this macro.
${SubFolder}	This macro is required to enable firmware upgrade operations that use this template to run simultaneously with other firmware upgrade operations. The macro resolves to the name of a subfolder that is automatically created on the SCP or TFTP server. To enable multiple firmware operations to run simultaneously, NCM copies the files for each operation to a uniquely named subfolder instead of to the root directory. You must use this macro to specify a subfolder. Do not enter a subfolder name.
${CRLF}	Use this macro to send the Enter command when a device asks confirmation questions. Also, when more than one command must be executed as part of an operation, use this macro to separate the commands.

Update config register command

This command is optional. If it is included, users performing an upgrade operation to select the Update config register option. An example of this command is:

config terminal${CRLF}config-register 0x2102${CRLF}end${CRLF}write memory${CRLF}${CRLF}${CRLF}

Update boot variable command

This command is optional, but SolarWinds recommends including it. If it is included, users performing an upgrade operation can select the Update boot variable option, which tells the device what image it should boot from after a reboot. If the boot variable is not updated, some devices might attempt to boot from the first image found on the device file system, and some devices might not boot at all.

An example of this command for non-ASA devices is:

config terminal${CRLF}no boot system${CRLF}boot system ${NewImageSlot}${NewImageName}${CRLF}end${CRLF}write memory${CRLF}${CRLF}${CRLF}show startup | include boot ${SuccessRegEx:${NewImageName}}

An example of this command for Cisco ASA devices is:

config terminal[Repeat:no ${BootItem}]boot system ${NewImageSlot}${NewImageName}${CRLF}end${CRLF}write memory${CRLF}${CRLF}${CRLF}show boot ${SuccessRegEx:${NewImageName}}

The following macros are used with this command.

Macro	Description
${NewImageName}	(Required for all devices.) This macro resolves to the name of the image name that is selected for the Update boot variable option during an upgrade operation.
${BootItem}	(Required for Cisco ASA devices.) For Cisco ASA devices, a separate no command must be sent for each boot path. The Collect Boot Variable Info command (issued during the information collection phase) saves all boot paths to the ${BootItem} macro, which is used in this command. The [Repeat:no ${BootItem}] construction repeats the command as many times as the number of values collected in the ${BootItem} macro. The Repeat statement works only with the ${BootItem} macro.
${NewImageSlot}	(Required for all devices.) This macro resolves to the value entered in the Path to upload image field during an upgrade operation (for example, flash: or disk0:).
${CRLF}	Use this macro to send the Enter command when a device asks confirmation questions. Also, when more than one command must be executed as part of an operation, use this macro to separate the commands.

Reboot command

This command is optional. If included, users performing an upgrade operation can select the Reboot device after upgrade option. An example of this command is:

reload${CRLF}y${CRLF}y

Verify uploaded firmware image integrity command

This command is optional. If it is included, users performing an upgrade operation can select the Verify uploaded firmware image integrity option. If that option is selected, NCM performs the following actions to verify that the image was transferred to the device correctly and not corrupted:

1. NCM executes the specified command to calculate the MD5 hash of the image on the NCM server.
2. NCM executes the same command to calculate the MD5 hash of the image that was transferred to the device.
3. NCM compares the values to confirm that they are the same.

For non-Nexus devices, the following example verifies the hash on a single image:

verify /md5 ${NewImageSlot}${NewImageName} ${NewImageHash} ${SuccessRegEx:Verified}

For Cisco Nexus devices, the following example verifies the hash on the system image and the kickstarter image:

show file ${NewImageSlot}${System.FileName} md5sum ${SuccessRegEx:${System.Hash}}${CRLF}show file ${NewImageSlot}${Kickstart.FileName} md5sum ${SuccessRegEx:${Kickstart.Hash}}

The following macros are used with this command.

Macro	Description
${NewImageSlot}	(Required for all devices.) This macro resolves to the value entered in the Path to upload image field during an upgrade operation (for example, flash: or disk0:).
${NewImageName}	(Required for non-Nexus devices.) This macro resolves to the name of the firmware image that is selected in the Firmware image(s) field during an upgrade operation.
${NewImageHash}	(Required for non-Nexus devices.) This macro resolves to the MD5 hash of the image file on the NCM server.
${System.FileName}	(Required for Nexus devices.) This macro resolves to the name of the system image that is selected in the Firmware image(s) field during an upgrade operation.
${System.Hash}	(Required for Nexus devices.) This macro resolves to the MD5 hash of the system image file on the NCM server.
${Kickstart.FileName}	(Required for Nexus devices.) This macro resolves to the name of the kickstart image that is selected in the Firmware image(s) field during an upgrade operation.
${Kickstart.Hash}	(Required for Nexus devices.) This macro resolves to the MD5 hash of the kickstart image file on the NCM server.
${CRLF}	Use this macro to send the Enter command when a device asks confirmation questions. Also, when more than one command must be executed as part of an operation, use this macro to separate the commands.
${SuccessRegEx:Verified}	(Required to perform verification for non-Nexus devices.) This macro determines if the command output (the hash value of the image uploaded to the device) matches the value of ${NewImageHash} (the hash value of the image on the server).
${SuccessRegEx:${System.Hash}}	(Required to perform verification for Nexus devices.) This macro determines if the command output (the hash value of the system image uploaded to the device) matches the value of ${System.Hash} (the hash value of the system image on the server).
${SuccessRegEx:${Kickstart.Hash}}	(Required to perform verification for Nexus devices.) This macro determines if the command output (the hash value of the kickstart image uploaded to the device) matches the value of ${Kickstart.Hash} (the hash value of the kickstart image on the server).

Verify backed up firmware image integrity command

This command is optional. If it is included, users performing an upgrade operation can select the Verify backed up firmware image integrity option. If that option is selected, NCM performs the following actions to verify that the image was backed up to the NCM server correctly and not corrupted:

1. NCM executes the specified command to calculate the MD5 hash of the image that was backed up to the NCM server.
2. NCM executes the same command to calculate the MD5 hash of the image that was transferred to the device.
3. NCM compares the values to confirm that they are the same.

An example of this command is:

verify /md5 ${ExistingImagePath} ${BackupImageHash} ${SuccessRegEx:Verified}

The following macros are used with this command.

Macro	Description
${ExistingImagePath}	(Required for all devices.) This macro resolves to the value entered in the Image path field for the Back up existing firmware image option during an upgrade operation.
${BackupImageHash}	(Required for all devices.) This macro resolves to the MD5 hash of the backed up image file on the NCM server.
${SuccessRegEx:Verified}	(Required to perform the verification.) This macro determines if the command output (the hash value of the image uploaded to the device) matches the value of ${BackupImageHash} (the hash value of the backed up image on the server).