Submit a ticketCall us

Have You Auto Renewed? If not, you're missing out.
The SolarWinds Renewal Program comes with a host of benefits including the most recent product updates, 24/7 technical support, virtual instructor-led training and more. Experience all of this with the convenience of Auto Renewal, and never worry about missing any of these great benefits. Learn More.

Home > Success Center > Network Configuration Manager (NCM) > NCM Firmware Upgrade Guide

NCM Firmware Upgrade Guide

Updated September 27, 2017

Overview

This article describes the commands and macros used by the Firmware Upgrade feature introduced in NCM 7.6.

Use this information to understand what each command does and the macros used by each command.

Environment

  • NCM 7.6 and later

Detail

Firmware upgrade templates contain all of the commands issued during the upgrade operation. Commands fall into two categories:

  • Collect Info commands
  • Upgrade commands

Collect Info Commands

When a user creates an upgrade operation and selects the desired nodes and firmware image, the first step NCM completes is to execute the "data collect" command. The purpose of executing “data collect” commands is to gather, from the devices, all required information to allow the user to review the operation and approve the run of the upgrade.

The output of running the data collect commands are available for the user to review on the Upgrade Options page.

The following commands are available in the template for this step.

Get current firmware image command

GetCurrentFirmwareImageCommand.png

The purpose of executing this command is to determine which image is currently used by the device. NCM will execute the specified command and try to capture information about the current image from the command output. What exactly to capture from the output is defined in the “Use capture results pattern” field.

For example, the standard Cisco IOS command to capture current image path is:

“show ver | include system image”

The capture results pattern for this command is:

‘System image file is "${CaptureData}"’

Once collected, NCM will search the command output for any line containing the string System image file is ".  If found, NCM captures all data between the quotation marks following System image file is. The part to be captured is defined by placing ${CaptureData} macros in the correct position in the line.

For example, running ‘show ver | include System image’ gives the following output:

System image file is "flash0:c2951-universalk9-mz.SPA.155-3.M1.bin"

As a result, given this output, NCM will capture flash0:c2951-universalk9-mz.SPA.155-3.M1.bin.

Why does NCM need this?

Information about the existing image path is used by NCM to pre-populate a TextBox field with the appropriate path when one of the following upgrade options are selected:

  • Delete existing firmware image
  • Backup existing firmware image

The same path used for the old image will be automatically pre-populated in the “Path to upload image” field on the Upgrade Options page.

Additionally, this information is used by the Free Space Detector when NCM is trying to evaluate if there is enough room available on the device to upload the new image. If NCM detects that there is not enough free space, it will try to determine if deleting the existing image will free up enough space to proceed.

What if this command is not specified?

This command is optional. If the user does not specify this command in the template, it will cause the following:

  • If the user decides to delete the existing firmware image during upgrade, they will need to manually specify the path to it on the Upgrade Options page.
  • If the user decides to back up the firmware image during upgrade, they will need to manually specify the path to it on the Upgrade Options page.
  • NCM's Free Space Detector will not be able to automatically determine if there is enough room to upload the new firmware image.

Get info on config register command

getInfoOnConfigRegister.png

The purpose of executing this command is to determine which config register option is active on the device. NCM will execute the specified command and try to capture the current config register value from the command output. What exactly to capture from the output is defined in the “Use capture results pattern” field in the same way as it was described above for the Get Current firmware image command.

NCM will attempt to capture the current value and compare it to the specified expected value. If the current value does not match the expected one, NCM will automatically enable the “Update Config Register” option on Upgrade Options page for the node in question.

Example:

show version

Cisco IOS Software, C2951 Software (C2951-UNIVERSALK9-M), Version 15.5(3)M1, RELEASE SOFTWARE (fc2)

Technical Support: http://www.cisco.com/techsupport

...

Configuration register is 0x2102

Different device models might require different config register values to allow the device to boot correctly after the upgrade. For example, for Cisco IOS the appropriate config register value is 0x2102. For Cisco ASA this is 0x1. For Cisco Catalyst the configuration register is not applicable.

Why does NCM need this?

Information about the config register is used by NCM to automatically enable the "Update Config Register" checkbox on the Upgrade Options page.

What if this command is not specified?

This command is optional. If the user does not specify this command in the template, it will cause the "Update Config Register" checkbox to be unchecked by default. The user will then need to manually check this box on the Upgrade Options page if necessary.

Get free space command

GetFreeSpaceCommand.png

NCM does not use the output of this command. The user can specify a command to be run to see the output on the Upgrade Options page to visually check, based on the command output, whether there is enough free space on the device. NCM uses its own Free Space Detector over SNMP to ensure that there is enough space available. However, NCM will perform the SNMP free space detection check if the customer specifies a "Get Free Space" CLI command. If  there are not any commands in the template, free space detection will not work.

Why does NCM need this?

NCM does not need this command. The output from the command is to let the customer ascertain if enough free space is available on the device. The Free Space Detector can also provide this information.

What if this command is not specified?

This command is optional, and NCM does not use the output.

Collect Boot Variable Info

CollectBootVariableInfo.png

This command was added in NCM V 7.7 to support firmware upgrade for Cisco ASA devices. There is a significant difference between a Cisco ASA and a Cisco IOS device when updating the boot variable (which image to load after reboot). The Cisco ASA must remove all existing boot paths (send a “no” command for each existing boot path it has (there may be more than one). This command will collect all existing device boot paths, and store the results into the ${BootItem} macro for use during the run of the Update Boot Variable command (which is described later in this document).

Why does NCM need this?

NCM needs this command to support updating the boot variable on Cisco ASA devices. NCM does not need this for any other model.

What if this command is not specified?

This command is used only for Cisco ASA devices.

If it is not specified, it will be not possible to run a firmware upgrade on a Cisco ASA device.

Other Commands (Optional)

OtherCommands.png

In this field, the user can specify commands they would like to see on the Upgrade Options page that may help make a decision whether to continue the firmware upgrade or not.

Why does NCM need this?

NCM does not need this command. This command is strictly for the user.

What if this command is not specified?

This command is optional, and NCM does not use the results for the operation.

Upgrade Commands

Upgrade commands run after the user confirms the node on the Upgrade Options page and starts the upgrade operation.

Upgrade firmware image command

UpgradeFirmwareImageCommand.png

This is the most important command and the only one that is mandatory. It must be present in the Firmware Upgrade template. The purpose of this command is to copy the firmware image from the TFTP server to the device file system. It will be always executed during an upgrade and does not depend on any upgrade options you choose.

Example:

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

In the case of any command customization, it is important to understand the macros used in the command. Some of these macros must be present in the command body of any template, but others are optional:

${TransferProtocol} – Will be parsed to specify in the template which transfer protocol to use (TFTP or SCP). This macro is optional. You can hard code the protocol name instead.

${StorageAddress} – Will be parsed to the NCM TFTP server IP address specified in NCM TFTP server settings. This macro is optional. You can hard code the IP address of the TFTP server in the command body instead.

${SCPStorageAddress} – If you choose to use the SCP protocol, use this SCP server IP address macro instead of the TFTP one. This macro is optional. You can hard code the IP address of the SCP server in the command body instead.

${SCPServerUserName} – Applicable only when SCP commands are in the template. It will be parsed to the configured SCP server user. This macro is optional. You can hard code the SCP server username in the command body instead.

${SCPServerPassword} – Applicable only when the SCP protocol is selected in the template. It will be parsed to the configured SCP server password. This macro is optional. You can hard code the SCP server password in the command body instead.

${NewImageName} – This macro is mandatory. NCM will parse it to the name of the firmware image that the user selected to upload to the device.

${NewImageSlot} – This macro is mandatory. NCM will parse it to the value that the user entered in the “Path to upload image” field on Upgrade Options page.

${CRLF} – This macro has two purposes:

  • When a device asks confirmation questions requiring the user to press Enter.
  • When more than one command must be executed as part of a copy image operation, the commands can be separated using this macro.

Operation safety checks

SolarWinds recommends putting safety check commands to ensure that each step completes appropriately, whenever possible. For example, after the copy image command in the default template, one more command is specified:

dir ${NewImageSlot} ${SuccessRegEx:${NewImageName}}

It was added to ensure that the new image file is now on the device's file system after the command execution. The dir command lists the files in the directory where NCM just uploaded the image. The ${SuccessRegEx:${NewImageName}} macro tells NCM to search in the output of the dir command for the name of newly uploaded file defined in the ${NewImageName} macro. If NCM cannot find the specified SuccessRegEx in the command output, the upgrade operation terminates and displays an error.

Delete firmware image command

This command is optional. If it is specified, the user will be able to select “Delete Existing Image” on the Upgrade options page. Enabling that option will execute this command during the upgrade.

Example:

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

Macros used:

${ExistingImagePath} – This macro is mandatory. It will be parsed to the value that the user enters in “Image path” for the “Delete existing firmware image” option on the Upgrade Options page.

${CRLF} – As part of the delete command, a device may ask a question like “Are you sure?” several times. In response to a question like this, use this macro to send the 'Enter' command.

Backup firmware image command

This command is optional. If it is specified, the user will be able to select “Backup Existing Firmware Image” on the Upgrade options page. Enabling that option executes this command during upgrade, which backs up the existing image into NCM firmware upgrade storage.

Example:

copy ${ExistingImagePath} ${TransferProtocol}://${StorageAddress}${CRLF}${CRLF}${CRLF}

Macros used:

${ExistingImagePath} – This macro is mandatory. It will be parsed to the value that the user enters in "Image path" for the "Backup existing firmware image" option on the Upgrade Options page.

If the SCP protocol is used, you must use the same SCP-specific macros described in the Upgrade firmware image command section. 

Update config register command

This command is optional. If it is specified, the user will be able to select the “Update Config Register” option on the Upgrade Options page. Enabling that option executes this command during the upgrade.

Example:

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

Macros used:

${CRLF} – Used to separate multiple commands.

Update boot variable command

This command is optional. However, SolarWinds recommends including it. It tells the device what image to boot from after a reboot. If it is not specified, some devices may not boot at all, and some of them may just try to boot from the first image found on the device file system. If it is specified, the user will be able to select the “Update Boot Variable” option on the Upgrade Options page. Enabling that option executes this command during upgrade

Example:

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}}

Macros used:

${NewImageName} – This macro is mandatory. It will be parsed to the value that the user enters as the image name for the “Update Boot Variable” option on the Upgrade Options page.

${NewImageSlot} – This macro is mandatory. It will be parsed to the value that the user enters in the “Path to upload image” field on Upgrade Options page to tell device where that new image is located (for example, flash: or disk0:).

${CRLF} – Used to separate multiple commands.

Operation safety checks

SolarWinds recommends including validation checks to ensure the boot variable is updated in the device startup config, because the startup config is the one used after reboot. The default template specifies the following additional command to accomplish this task.

show startup | include boot ${SuccessRegEx:${NewImageName}}

This command searches the startup config boot variable line. The macro ${SuccessRegEx:${NewImageName}} ensures that the command output contains new the image name.

Cisco ASA Extension

As previously described, the Cisco ASA has special requirements to update the boot variable. It is not possible to just send the ‘no boot system’ command to delete the existing boot path and specify a new one. If multiple boot paths are in need of removal, there is a separate 'no' command for each registered path. As you remember, all existing boot paths on the device were collected by the “Collect Boot Variable Info” command into the ${BootItem} macro. To update the boot variable on a Cisco ASA device, we need to use that collected info.

Example:

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

The [Repeat:no ${BootItem}] construction tells NCM to repeat the command as many times as the number of values we have collected in BootItem macro.

Example:

NCM has collected the following list of boot paths:

boot system flash:/image1.bin

boot system flash:/image2.bin

As a result, NCM will parse [Repeat:no ${BootItem}] to the following lines:

No boot system flash:/image1.bin

No boot system flash:/image2.bin

The Repeat statement currently works only with the ${BootItem} macro. It will not work with any other macro. In the future, additional macros may be added for other device types if needed.

Reboot command

This command is optional. If it is specified, the user will be able to select the “Reboot Device After Upgrade” option on the Upgrade Options page. Enabling that option executes this command during the upgrade

Example:

reload${CRLF}y${CRLF}y

Macros used:

${CRLF} – Used to respond to device confirmation questions.

Verify uploaded firmware image integrity command

This command is optional. If it is specified, the user will be able to select the “Verify uploaded firmware image integrity” option on the Upgrade Options page. Enabling that option executes thiscommand during the upgrade.

Example:

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

The purpose of this command is to verify the integrity of the image after the transfer from NCM to the device is complete. To do so, NCM calculates the MD5 hash of the image on the server side. After that, this command is executed again to calculate the MD5 hash of the file on the device, and compare it to the hash calculated on the NCM server. If the hash is equal, it means the image was transferred correctly and not corrupted.

Macros used:

${NewImageName} – This macro is mandatory. It is parsed to the name of the firmware image that the user selected to upload on the device.

${NewImageSlot} – This macro is mandatory. It is parsed to the value the user entered in the “Path to upload image” field on the Upgrade Options page.

${NewImageHash} – This macro is mandatory. It is parsed to the MD5 hash of the newly uploaded firmware image file calculated on NCM server side.

Operation safety checks

We need to know if the MD5 hash calculated on the device matches the hash calculated on the NCM server. As part of the command, we already provided the hash calculated on the NCM server, and we need to know from the command output if the hash matches the one calculated on the device side. To find out, include the ${SuccessRegEx:Verified} macro. It determines if the command response contains the word “Verified”, which means that both hashes match. Without verification of the command output, there is no reason to perform this operation.

Verify backed up firmware image integrity command

This command is optional. If it is specified, the user will be able to select the “Verify backed up firmware image integrity” option on the Upgrade Options page. Enabling that option executes this command during upgrade

Example:

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

The purpose of this command is to verify the integrity of the image after the transfer from the device to the NCM server (the opposite direction from the previous command). To do so, NCM calculates the MD5 hash of the backed up image on the server side. After that, this command is executed again to calculate the MD5 hash of the file on the device, and compare it to hash calculated on the NCM server. If the hash is equal, it means the image was transferred correctly and not corrupted.

Macros used:

${ExistingImagePath} – This macro is mandatory. It will be parsed to the value that the user entered in the “Image path” for the “Backup existing firmware image” option on the Upgrade Options page.

${BackupImageHash} – This macro is mandatory. It is parsed to the MD5 hash of the backed up firmware image file calculated on NCM server side.

Operation safety checks

We need to know if the MD5 hash calculated on the device matches the hash calculated on NCM server. As part of the command, we already provided hash calculated on the NCM server, and we need to know from the command output if the hash matches. To find out, include the ${SuccessRegEx:Verified} macro. It determines if the command response contains the word “Verified”, which means that both hashes match. Without verification of the command output, there is no reason to perform this operation.

Macros Mapping Summary

The following images provide a summary of where macro values come from:

MacrosMappingSummary.png

 

FirmwareRepository.png

 

EditFirmwareUpgradeTemplate.png

 

 

Last modified

Tags

Classifications

Public