The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
This chapter describes how to configure the Configure Replace feature.
Your software release might not support all the features documented in this module. For the latest caveats and feature information, see the Bug Search Tool at https://tools.cisco.com/bugsearch/ and the release notes for your 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 “New and Changed Information” section or the "Feature History" table.
The configuration replace feature enables you to replace the running configuration of the Cisco Nexus switch with the user provided configuration without reloading the device. The device reload may be required only when a configuration itself requires a reload. The user provided configuration is the running configuration that is received with the Cisco NX-OS device. Unlike copy file: to running, the configuration replace feature is not a merge operation. This feature replaces the entire running configuration with a new configuration that is provided by the user. If there is a failure in the configuration replace, the original configuration is restored in the switch.
The commit-timeout feature enables you to rollback to the previous configuration after successfully performing the configuration replace operation. If the commit timer expires, the rollback operation is automatically initiated.
The commit-timeout feature is initiated only if you perform the configuration replace operation with the commit-timeout. The timer value range is between 30-3600 seconds.
 Note |
The class type queuingnew-class-policy command in the running configuration causes a config-replace failure in Cisco Nexus 7700 Series platform in Cisco NX-OS Release 8.2(1). It is recommended that you remove the class type queuingnew-class-policy command from the running or target configuration to prevent the config-replace failure. |
Overview
The configuration replace feature leverages the current rollback infrastructure with operation steps as follows:
Configuration replace intelligently calculates the difference between the current running-configuration and the user-provided configuration in the Cisco Nexus switch and generates a patch file which is the difference between the two files. You can view this patch file which includes a set of configuration commands.
Configuration replace applies the configuration commands from the patch file similarly to executing commands.
Note |
Since the configuration replace feature is atomic, if there are any errors while applying the configuration, it breaks at that point and then restores the switch to the original running configuration. |
The configuration rolls back to or restores the previous running configuration under the following situations:
If there is a mismatch in the configuration after the patch file has been applied.
If you perform the configuration operation with a commit timeout and the commit timer expires.
You can view the exact configuration that caused a failure using the show config-replace log exec command.
Restore operations that fail while restoring the switch to the original configuration, are not interrupted. The restore operation continues with the remaining configuration. Use the show config-replace log exec command to list the commands that failed during the restore operation.
If you enter the configure replace commit command before the timer expires, the commit timer stops and the switch runs on the user provided configuration that has been applied through the configuration replace feature.
If the commit timer expires, roll back to the previous configuration is initiated automatically.
The differences between configuration replace and copying a file to the running-configuration are as follows:
|
Configuration Replace |
Copying a file |
|---|---|
|
The configure replace <target-url> command removes the commands from the current running-configuration that are not present in the replacement file. It also adds commands that need to be added to the current running-configuration. |
The copy <source-url> running-config command is a merge operation which preserves all the commands from, both the source file and the current running-configuration. This command does not remove the commands from the current running-configuration that are not present in the source file. |
|
You must use a complete Cisco NX-OS configuration file as the replacement file for the configure replace <target-url> command. |
You can use a partial configuration file as a source file for the copy <source-url> running-config command. |
Benefits of Configure Replace
The benefits of configuration replace are:
You can replace the current running-configuration file with the user-provided configuration file without having to reload the switch or manually undo CLI changes to the running-configuration file. As a result, the system downtime is reduced.
You can revert to the saved Cisco NX-OS configuration state.
It simplifies the configuration changes by allowing you to apply a complete configuration file to the device, where only the commands that need to be added or removed are affected. The other service and configurations that are not modified remain untouched.
If you configure the commit-timeout feature, you can rollback to the previous configuration even when the configuration replace operation has been successful.
Prerequisites for Configure Replace
You need to provide the valid running-configuration taken from the Nexus device. It should not be a partial configuration.
Guidelines and Limitations of Configure Replace
The CR feature has the following configuration guidelines and limitations:
Commit timeout feature is added in CR in Cisco NX-OS Release 8.3(1).
The commit-timeout feature is initiated only if you perform the configuration replace operation with the commit-timeout. The timer value range is between 30-3600 seconds.
The user configuration file to which you need to replace the running configuration on the switch using CR should be generated from the running-config of the switch after configuring the new commands. The user configuration file should not be manually edited with the CLI commands and the sequence of the configuration commands should not be altered.
The configuration file must be regenerated whenever there is change in the software version.
It is recommended not to do any of the configuration changes from any other session when CR is in progress. This is to avoid CR failure.
CR request is serialized; only after the first request is complete the next request is processed.
CR does not work if the FEX module is offline.
CR is not supported on port profiles that are inherited on the switch interfaces.
CR fails if it contains module-specific configuration and if the module is not online.
CR is supported only for configure terminal mode and configure maintenance mode commands. Configure profile, configure job and any other modes are not supported. Maintenance mode is supported from Cisco NX-OS Release 8.3(1).
User configuration file must be show run and not show run vdc-all. Configurations taken in one VDC is not applicable to the other VDC.
CR is not supported on an admin VDC. CR is supported only on the default and non-default VDCs.
You can perform a parallel CR between different VDCs. For example, user1 can execute CR on VDC1, and user2 can execute CR on VDC2 at the same time, and they will not impact each other.
To perform parallel CR for more than one VDC; go to the VDC where CR needs to be performed (using the vdc <vdc-name> command) and execute the configure replace <file-name> command.
CR is supported on Supervisor 3 and Fabric Module 3. Starting from Cisco NX-OS 8.4(1), CR is also supported on F4 Series Modules.
Starting from Cisco NX-OS 8.4(1), CR is supported for breakout interface configurations.
The following steps describe the recommended workflow for CR:
You can generate a configuration file by first applying the configurations on a Cisco Nexus series switch and then use the copy run file output as the configuration file. This file should be the file where you can make configuration modification as required and use this generated/updated configuration file to perform configuration replace. Make sure the syntax/format for the edited configuration to be same as shown in the running configuration.
The configuration file must be regenerated whenever there is change in software version. The CR operation on configuration file generated across software version is not recommended and CR might fail or succeed.
You can view and verify the patch file before it gets applied by executing configure replace <file> show-patch command.
Run the configuration replace file either using or skipping the commit-timeout feature. Based on your requirements, you can perform one of the following steps:
You can run configure replace <file> verbose to see the commands that get executed with CR on console.
Run the configure replace [bootflash/scp/sftp] <user-configuration-file> verbose commit-timeout <time> commands to configure the commit time.
Run the configure replace commit command to stop the commit timer. This step is necessary if you have run the configuration replace operation with the commit-timeout feature.
CR will do pre-check which includes semantic validation of configuration, and in case of error CR exits. The user can use show config-replace log verify command to see exact configurations that failed.
CR is atomic, in case of failure, the CR exits on the first failure and restores the switch to original configuration. You can use show config-replace log exec command to get the error display.
Once patch is applied, CR triggers verification where it compares the running-configuration matches with user configuration file, if there is mismatch it restores the switch. You can use show config-replace verify command to see mismatched configurations.
It is recommended not to modify any configuration through other session when CR in progress.
To perform configuration replace, do the following:
| Command or Action | Purpose | |||||
|---|---|---|---|---|---|---|
|
Step 1 |
configure replace { <uri_local > | <uri_remote > } [verbose | show-patch ] |
Performs configuration replace. If you make the configuration changes through any sessions when configuration replace is in progress, the configuration replace operation fails. If you send a configuration replace request when one configuration request is already in progress, then it gets serialized. |
||||
|
Step 2 |
configure replace [bootflash /scp /sftp ] <user-configuration-file > show-patch |
Displays the differences between the running-configuration and the user-provided configuration. |
||||
|
Step 3 |
configure replace [bootflash /scp /sftp ] <user-configuration-file > verbose |
Replaces the configuration on the switch with the new user configuration that is provided by the user. Configuration replace is always atomic. |
||||
|
Step 4 |
(Optional) configure replace bootflash /scp /sftp ] <user-configuration-file > verbose commit-timeout time |
(Optional)
Configures the commit time in seconds. The timer starts after the configuration replace operation is successfully completed. |
||||
|
Step 5 |
(Optional) configure replace [commit ] |
(Optional)
|
||||
|
Step 6 |
(Optional) configure replace bootflash /scp /sftp ] <user-configuration-file > non-interactive |
(Optional)
There is no user prompt in maintenance mode. The yes user-confirmation is taken by default, and rollback proceeds. The non-interactive option can be used only in the maintenance mode. |
The following commands are used to verify the status of the configure replace operation.
| Command or Action | Purpose | |
|---|---|---|
|
Step 1 |
configure replace [bootflash /scp /sftp ] <user-configuration-file> ] show-patch |
Displays the difference between the running-configurations and user-provided configurations. |
|
Step 2 |
show config-replace log exec |
Displays a log of all the configurations executed and those that failed. In case of an error, it displays an error message against that configuration. |
|
Step 3 |
show config-replace log verify |
Displays the configurations that failed, along with an error message. It does not display configurations that were successful. |
|
Step 4 |
show config-replace status |
Displays the status of the configuration replace operations, including in-progress, successful, and failure. If you have configured the commit-timeout feature, the commit and timer status and the commit timeout time remaining is also displayed. |
See the following configuration examples for configure replace:
Use the configure replace bootflash: <file> show-patch CLI command to display the difference between the running-configurations and user-provided configurations.
switch(config)# configure replace bootflash:<file> show-patch
Collecting Running-Config
Converting to checkpoint file
#Generating Rollback Patch
!!
no role name abcUse the configure replace bootflash: <file> verbose CLI command to replace the entire running-configuration in the switch with the user-configuration.
switch(config)# configure replace bootflash:<file> verbose
Collecting Running-Config
Generating Rollback patch for switch profile
Rollback Patch is Empty
Note: Applying config parallelly may fail Rollback verification
Collecting Running-Config
#Generating Rollback Patch
Executing Rollback Patch
========================================================
config t
no role name abc
========================================================
Generating Running-config for verification
Generating Patch for verification
Rollback completed successfully.
Sample Example with adding of BGP configurations.
switch(config)# sh run | section bgp
switch(config)# sh file bootflash:file | section bgp
feature bgp
router bgp 1
address-family ipv4 unicast
neighbor 1.1.1.1
switch(config)#
switch(config)# configure replace bootflash:file verbose
Collecting Running-Config
Generating Rollback patch for switch profile
Rollback Patch is Empty
Note: Applying config parallelly may fail Rollback verification
Collecting Running-Config
#Generating Rollback Patch
Executing Rollback Patch
========================================================
config t
feature bgp
router bgp 1
address-family ipv4 unicast
neighbor 1.1.1.1
========================================================
Generating Running-config for verification
Generating Patch for verification
Rollback completed successfully.
switch(config)# sh run | section bgp
feature bgp
router bgp 1
address-family ipv4 unicast
neighbor 1.1.1.1
Sample Example with ACL
switch(config)# configure replace bootflash:run_1.txt
Collecting Running-Config
Generating Rollback patch for switch profile
Rollback Patch is Empty
Note: Applying config parallelly may fail Rollback verification
Collecting Running-Config
#Generating Rollback Patch
Executing Rollback Patch
========================================================
config t
no ip access-list nexus-50-new-xyz
ip access-list nexus-50-new-xyz-jkl-abc
10 remark Newark
20 permit ip 17.31.5.0/28 any
30 permit ip 17.34.146.193/32 any
40 permit ip 17.128.199.0/27 any
50 permit ip 17.150.128.0/22 any
========================================================
Generating Running-config for verification
Generating Patch for verification
Rollback completed successfully.
switch(config)#
switch(config)# show run aclmgr | sec nexus-50-new-xyz-jkl-abc
ip access-list nexus-50-new-xyz-jkl-abc
10 remark Newark
20 permit ip 17.31.5.0/28 any
30 permit ip 17.34.146.193/32 any
40 permit ip 17.128.199.0/27 any
50 permit ip 17.150.128.0/22 anyUse the show config-replace log exec CLI command to check all the configuration that is executed and failures if any.
switch(config)# show config-replace log exec
Operation : Rollback to Checkpoint File
Checkpoint file name : .replace_tmp_28081
Scheme : tmp
Rollback done By : admin
Rollback mode : atomic
Verbose : enabled
Start Time : Wed, 06:39:34 25 Jan 2017
--------------------------------------------------------------------------------
time: Wed, 06:39:47 25 Jan 2017
Status: SUCCESS
End Time : Wed, 06:39:47 25 Jan 2017
Rollback Status : Success
Executing Patch:
----------------
switch#config t
switch#no role name abc
Use the show config-replace log verify CLI command to check the failed configuration if any.
switch(config)# show config-replace log verify
Operation : Rollback to Checkpoint File
Checkpoint file name : .replace_tmp_28081
Scheme : tmp
Rollback done By : admin
Rollback mode : atomic
Verbose : enabled
Start Time : Wed, 06:39:34 25 Jan 2017
End Time : Wed, 06:39:47 25 Jan 2017
Status : Success
Verification patch contains the following commands:
---------------------------------------------------
!!
! No changes
--------------------------------------------------------------------------------
time: Wed, 06:39:47 25 Jan 2017
Status: SUCCESS
Use the show config-replace status CLI command to check the status of configuration replace.
switch(config)# show config-replace status
Last operation : Rollback to file
Details:
Rollback type: atomic replace_tmp_28081
Start Time: Wed Jan 25 06:39:28 2017
End Time: Wed Jan 25 06:39:47 2017
Operation Status: Success
switch(config)#
Configure Replace might fail when the manually created configuration has been used instead of the configuration generated from the switch. The reason for possible failures is the potential difference in the default configuration that is not shown in the show running configuration. Refer to the following examples:
If the power redundant command is the default command, it does not get displayed in the default configuration. But it is displayed when you use the show run all command. An example is given below.
switch# show run all
!Command: show running-config all
!Running configuration last done at: Tue Nov 12 11:07:44 2019
!Time: Tue Nov 12 11:16:09 2019
version 8.4(1) Bios:version 05.39
power redundancy-mode ps-redundant
no hardware module boot-order reverse
no license grace-period
<snip>
hostname brno
The power redundant command is not shown in the show running configuration command output. An example is given below.
!Command: show running-config
!Running configuration last done at: Tue Nov 12 11:07:44 2019
!Time: Tue Nov 12 11:17:24 2019
version 8.4(1) Bios:version 05.39
hostname brno
When the power redundancy-mode ps-redundant command is added in the user configuration to be used in configure replace; then the verification/commit might fail. An example is given below.
switch# show file bootflash:test
!Command: show running-config
!Running configuration last done at: Tue Nov 12 10:56:49 2019
!Time: Tue Nov 12 11:04:57 2019
version 8.4(1) Bios:version 05.39
power redundancy-mode ps-redundant
hostname brno
The power redundancy-mode ps-redundant command will not be shown in the show running command output after the configure replace; therefore it will be considered as “missing” and the CR will fail. An example is given below.
switch# config replace bootflash:test verify-and-commit
Version match between user file and running configuration.
Pre-check for User config PASSED
ADVISORY: Config Replace operation started...
Modifying running configuration from another VSH terminal in parallel
is not recommended, as this may lead to Config Replace failure.
Collecting Running-Config
Generating Rollback patch for switch profile
Rollback Patch is Empty
Collecting Running-Config
.Generating Rollback Patch
Validating Patch
Patch validation completed successful
Executing Rollback Patch
During CR operation,will retain L3 configuration
when vrf member change on interface
Generating Running-config for verification
Generating Rollback Patch
Executing Rollback Patch
During CR operation,will retain L3 configuration
when vrf member change on interface
Generating Running-config for verification
Generating Patch for verification
Verification failed, Rolling back to previous configuration
Collecting Running-Config
Cleaning up switch-profile buffer
Generating Rollback patch for switch profile
Executing Rollback patch for switch profiles. WARNING - This will change the configuration of switch profiles and will also affect any peers if configured
Collecting Running-Config
Generating Rollback Patch
Rollback Patch is Empty
Rolling back to previous configuration is successful
Configure replace failed. Use 'show config-replace log verify' or 'show config-replace log exec' to see reasons for failure
Configure replace failed. Use 'show config-replace log verify' or 'show config-replace log exec' to see reasons for failure
brno# show config-replace log verify
Operation : Config-replace to user config
Checkpoint file name : .replace_tmp_31849
Scheme : tmp
Cfg-replace done By : agargula
Cfg-replace mode : atomic
Verbose : disabled
Start Time : Tue, 11:20:59 12 Nov 2019
Start Time UTC : Tue, 10:20:59 12 Nov 2019
-------------------------------------------
End Time : Tue, 11:21:28 12 Nov 2019
End Time UTC : Tue, 10:21:28 12 Nov 2019
Status : Failed
Verification patch contains the following commands:
---------------------------------------------------
!!
Configuration To Be Added Missing in Running-config
===================================================
!
power redundancy-mode ps-redundant
Undo Log
--------------------------------------------------------------------------------
End Time: Tue, 11:21:32 12 Nov 2019
End Time UTC : Tue, 10:21:32 12 Nov 2019
Status : Success
brno#
In the above example, CR will consider the default commands that are missing and will therefore fail.
Feedback