Managing Configuration Files Configuration Guide, Cisco IOS XE Release 3SE (Catalyst 3850 Switches)
Configuration Replace and Configuration Rollback
Downloads: This chapterpdf (PDF - 171.0KB) The complete bookPDF (PDF - 589.0KB) | The complete bookePub (ePub - 704.0KB) | Feedback

Configuration Replace and Configuration Rollback

Configuration Replace and Configuration Rollback

Last Updated: January 23, 2013

The Configuration Replace and Configuration Rollback feature enables you to replace the current running configuration with any saved Cisco configuration file. You can use this functionality to revert the configuration to a previous state, effectively rolling back any configuration changes that were made since that configuration file was saved.

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 Configuration Replace and Configuration Rollback

The format of the configuration files used as input by the Configuration Replace and Configuration Rollback feature must comply with standard Cisco software configuration file indentation rules as follows:

  • Start all commands on a new line with no indentation, unless the command is within a configuration submode.
  • Indent commands within a first-level configuration submode one space.
  • Indent commands within a second-level configuration submode two spaces.
  • Indent commands within subsequent submodes accordingly.

These indentation rules describe how the software creates configuration files for such commands as show running-config or copy running-config destination-url. Any configuration file generated on a Cisco device complies with these rules.

Free memory larger than the combined size of the two configuration files (the current running configuration and the saved replacement configuration) is required.

Restrictions for Configuration Replace and Configuration Rollback

If the device does not have free memory larger than the combined size of the two configuration files (the current running configuration and the saved replacement configuration), the configuration replace operation is not performed.

Certain Cisco configuration commands such as those pertaining to physical components of a networking device (for example, physical interfaces) cannot be added or removed from the running configuration. For example, a configuration replace operation cannot remove the interface ethernet 0 command line from the current running configuration if that interface is physically present on the device. Similarly, the interface ethernet 1 command line cannot be added to the running configuration if no such interface is physically present on the device. A configuration replace operation that attempts to perform these types of changes results in error messages indicating that these specific command lines failed.

In very rare cases, certain Cisco configuration commands cannot be removed from the running configuration without reloading the device. A configuration replace operation that attempts to remove this type of command results in error messages indicating that these specific command lines failed.

Information About Configuration Replace and Configuration Rollback

Configuration Replace Operation

The configure replace command allows you to replace the current running configuration with any saved Cisco configuration file. You can use this functionality to revert the configuration to a previous state, effectively rolling back any configuration changes that were made since the previous configuration state was saved.

When using the configure replace command, you must specify a saved Cisco configuration as the replacement configuration file for the current running configuration. The replacement file must be a complete configuration generated by a Cisco device (for example, a configuration generated by the copy running-config destination-url command). Or, the replacement file is generated externally from a Cisco device, the file must comply with the format of files generated by Cisco devices. When the configure replace command is entered, the current running configuration is compared with the specified replacement configuration and a set of differences (diffs) is generated. The algorithm used to compare the two files is the same as that used by the show archive config differences command. The resulting diffs are then applied by the Cisco parser to achieve the replacement configuration state. Only the diffs are applied, avoiding potential service disruption from reapplying configuration commands that already exist in the current running configuration. This algorithm effectively handles configuration changes to order-dependent commands (such as access lists) through a multiple pass process. Under normal circumstances, no more than three passes are needed to complete a configuration replace operation, and a limit of five passes is performed to preclude any looping behavior.

The copy source-url running-config command is often used to copy a stored configuration file to the running configuration. When you use the copy source-url running-config command as an alternative to the configure replace target-url command, you should be aware of the following major differences:

  • The copy source-url running-config command is a merge operation and preserves all the commands from both the source file and the current running configuration. This command does not remove commands from the current running configuration that are not present in the source file. In contrast, the configure replace target-url command removes commands from the current running configuration that are not present in the replacement file and adds commands to the current running configuration that need to be added.
  • The copy source-url running-config command applies every command in the source file, whether or not the command is already present in the current running configuration. This algorithm is inefficient and, in some cases, can result in service outages. In contrast, the configure replace target-url command only applies the commands that need to be applied--no existing commands in the current running configuration are reapplied.
  • A partial configuration file can be used as the source file for the copy source-url running-config command, whereas a complete Cisco configuration file must be used as the replacement file for the configure replace target-url command.

When the configure replace command is used, the running configuration file is locked by default through the Exclusive Configuration Change Access feature (also known as the Configuration Lock feature) for the duration of the configuration replace operation. This locking mechanism prevents other users from changing the running configuration while the replacement operation is taking place, which might otherwise cause the replacement operation to terminate unsuccessfully. You can disable the locking of the running configuration by using the configure replace nolock command.

The running configuration lock is automatically cleared at the end of the configuration replace operation. You can display any locks that might be applied to the running configuration by using the show configuration lock command.

Configuration Rollback Operation

The concept of rollback comes from the transactional processing model common to database operations. In a database transaction, you might make a set of changes to a given database table. You then must choose whether to commit the changes (apply the changes permanently) or to roll back the changes (discard the changes and return to the previous state of the table). In this context, rollback means that a journal file containing a log of the changes is discarded, and no changes are applied. The result of the rollback operation is to return to the previous state, before any changes were applied.

The configure replace command allows you to revert the configuration to a previous state, effectively rolling back changes that were made since the previous configuration state was saved. Instead of basing the rollback operation on a specific set of changes that were applied, the Cisco configuration rollback capability uses the concept of returning to a specific configuration state based on a saved Cisco configuration file. This concept is similar to the database idea of saving a checkpoint (a saved version of the database) to preserve a specific state.

If the configuration rollback capability is desired, you must save the running configuration before making any configuration changes. Then, after entering configuration changes, you can use that saved configuration file to roll back the changes (by using the configure replace target-url command). Furthermore, because you can specify any saved Cisco configuration file as the replacement configuration, you are not limited to a fixed number of rollbacks, as is the case in some rollback models based on a journal file.

Benefits of Configuration Replace and Configuration Rollback

The Configuration Replace and Configuration Rollback feature has these benefits:

  • Allows you to revert a configuration to a previous state, effectively rolling back configuration changes.
  • Allows you to replace the current running configuration file with the startup configuration file without having to reload the device or manually undo CLI changes to the running configuration file, therefore reducing system downtime.
  • Allows you to revert to any saved Cisco configuration state.
  • Simplifies 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.
  • When you use the configure replace command as an alternative to the copy source-url running-config command, it increases efficiency and prevents risk of service outages by not reapplying existing commands in the current running configuration.

How to Use Configuration Replace and Configuration Rollback

Performing a Configuration Replace or Configuration Rollback Operation with Confirmation

Perform this task to replace the current running configuration file with a saved Cisco configuration file.


Note


You must configre a configuration archive before performing this procedure. For detailed steps, see the "Configuring the Characteristics of the Configuration Archive" module in the Managing Configuration Files Configuration Guide. The following procedure details how to return to that archived configuration in the event of a problem with the current running configuration.
SUMMARY STEPS

1.    enable

2.    configure replace target-url [nolock] [list] [force] [ignorecase] [revert trigger [error] [timer minutes] | time minutes]

3.    configure revert {now | timer {minutes | idle minutes}}

4.    configure confirm

5.    exit


DETAILED STEPS
  Command or Action Purpose
Step 1
enable


Example:

Device> enable

 

Enables privileged EXEC mode.

  • Enter your password if prompted.
 
Step 2
configure replace target-url [nolock] [list] [force] [ignorecase] [revert trigger [error] [timer minutes] | time minutes]


Example:

Device# configure replace bootflash:myconfig-1 list time 30

 

Replaces the current running configuration file with a saved configuration file.

  • target-url--Specifies a URL (accessible by the Cisco file system) of the saved configuration file that is to replace the current running configuration, such as the configuration file created by using the archive config command. Depending on your hardware platform, the name of your file system might be different than shown in the example.
  • nolock--Disables the locking of the running configuration file that prevents other users from changing the running configuration during a configuration replace operation.
  • list--Displays a list of the command lines applied by the Cisco software parser during each pass of the configuration replace operation. The total number of passes performed is also displayed.
  • force--Replaces the current running configuration file with the specified saved configuration file without prompting you for confirmation.
  • ignorecase--Allows the configuration to ignore the case of the confirmation command.
  • time minutes--Specifies the time (in minutes) within which you must enter the configure confirm command to confirm replacement of the current running configuration file. If the configure confirm command is not entered within the specified time limit, the configuration replace operation is automatically reversed (in other words, the current running configuration file is restored to the configuration state that existed prior to entering the configure replace command).
  • revert trigger--Sets the following triggers for reverting to the original configuration:
    • error--Reverts to the original configuration upon error.
    • timer minutes--Reverts to the original configuration if the specified time elapses.
 
Step 3
configure revert {now | timer {minutes | idle minutes}}


Example:

Device# configure revert now

 

(Optional) Cancels the timed rollback and triggers the rollback immediately or resets parameters for the timed rollback.

  • now--Triggers the rollback immediately.
  • timer--Resets the configuration revert timer.
    • Use the minutes argument with the timer keyword to specify a new revert time in minutes.
    • Use the idle keyword along with a time in minutes to set the maximum allowable time period of no activity before reverting to the saved configuration.
 
Step 4
configure confirm


Example:

Device# configure confirm

 

(Optional) Confirms replacement of the current running configuration file with a saved configuration file.

Note    Use this command only if the time minutes keyword and argument of the configure replace command are specified.
 
Step 5
exit


Example:

Device# exit

 

Exits to user EXEC mode.

 

Monitoring and Troubleshooting the Configuration

SUMMARY STEPS

1.    enable

2.    show archive

3.    debug archive versioning

4.    debug archive config timestamp

5.    exit


DETAILED STEPS
Step 1   enable

Use this command to enable privileged EXEC mode. Enter your password if prompted. For example:



Example:
Device> enable
Device#
Step 2   show archive

Use this command to display information about the files saved in the configuration archive. For example:



Example:
Device# show archive

There are currently 1 archive configurations saved.
The next archive file will be named bootflash:myconfig-2
 Archive #  Name
   0 
   1       bootflash:myconfig-1 <- Most Recent
   2 
   3 
   4 
   5 
   6 
   7 
   8 
   9 
   10 
   11 
   12 
   13 
   14 

The following is sample output from the show archive command after several archive files of the running configuration have been saved. In this example, the maximum number of archive files to be saved is set to three.



Example:
Device# show archive

There are currently 3 archive configurations saved.
The next archive file will be named bootflash:myconfig-8
 Archive #  Name
   0        
   1       :Deleted
   2       :Deleted
   3       :Deleted
   4       :Deleted
   5       bootflash:myconfig-5
   6       bootflash:myconfig-6
   7       bootflash:myconfig-7 <- Most Recent
   8
   9
   10
   11
   12
   13
   14
Step 3   debug archive versioning

Use this command to enable debugging of the configuration archive activities to help monitor and troubleshoot configuration replace and rollback. For example:



Example:
Device# debug archive versioning
Jan  9 06:46:28.419:backup_running_config
Jan  9 06:46:28.419:Current = 7
Jan  9 06:46:28.443:Writing backup file bootflash:myconfig-7
Jan  9 06:46:29.547: backup worked
Step 4   debug archive config timestamp

Use this command to enable debugging of the processing time for each integral step of a configuration replace operation and the size of the configuration files being handled. For example:



Example:
Device# debug archive config timestamp
Device# configure replace bootflash:myconfig force
Timing Debug Statistics for IOS Config Replace operation:
       Time to read file slot0:sample_2.cfg = 0 msec (0 sec)
       Number of lines read:55
       Size of file        :1054
Starting Pass 1
       Time to read file system:running-config = 0 msec (0 sec)
       Number of lines read:93
       Size of file        :2539
       Time taken for positive rollback pass = 320 msec (0 sec)
       Time taken for negative rollback pass = 0 msec (0 sec)
       Time taken for negative incremental diffs pass = 59 msec (0 sec)
       Time taken by PI to apply changes = 0 msec (0 sec)
       Time taken for Pass 1 = 380 msec (0 sec)
Starting Pass 2
       Time to read file system:running-config = 0 msec (0 sec)
       Number of lines read:55
       Size of file        :1054
       Time taken for positive rollback pass = 0 msec (0 sec)
       Time taken for negative rollback pass = 0 msec (0 sec)
       Time taken for Pass 2 = 0 msec (0 sec)
Total number of passes:1
Rollback Done
Step 5   exit

Use this command to exit to user EXEC mode. For example:



Example:
Device# exit
Device>

Configuration Examples for Configuration Replace and Configuration Rollback

Example: Replacing the Current Running Configuration with a Saved Configuration File

The following example shows how to replace the current running configuration with a saved Cisco configuration file named bootflash:myconfig. The configure replace command interactively prompts you to confirm the operation. Depending on your hardware platform, the name of your file system might be different than shown in the example.

Device# configure replace bootflash:myconfig
This will apply all necessary additions and deletions
to replace the current running configuration with the
contents of the specified configuration file, which is
assumed to be a complete configuration, not a partial
configuration. Enter Y if you are sure you want to proceed. ? [no]: Y
Total number of passes: 1
Rollback Done

In the following example, the list keyword is specified in order to display the command lines that were applied during the configuration replace operation:

Device# configure replace bootflash:myconfig list
This will apply all necessary additions and deletions
to replace the current running configuration with the
contents of the specified configuration file, which is
assumed to be a complete configuration, not a partial
configuration. Enter Y if you are sure you want to proceed. ? [no]: Y
!Pass 1
!List of Commands:
no snmp-server community public ro
snmp-server community mystring ro                                                                  
end
Total number of passes: 1
Rollback Done

Example: Reverting to the Startup Configuration File

The following example shows how to revert to the Cisco configuration file using the configure replace command. This example also shows the use of the optional force keyword to override the interactive user prompt.

Device# configure replace nvram:startup-config force
Total number of passes: 1
Rollback Done

Example: Performing a Configuration Rollback Operation

The following example shows how to make changes to the current running configuration and then roll back the changes. As part of the configuration rollback operation, you must save the current running configuration before making changes to the file. In this example, the archive config command saves the current running configuration. The generated output of the configure replace command indicates that only one pass was performed to complete the rollback operation.


Note


Before using the archive config command, you must configure the path command to specify the location and filename prefix for the files in the Cisco configuration archive.

You first save the current running configuration in the configuration archive as follows:

archive config

You then enter configuration changes as shown in the following example:

configure terminal
!
user netops2 password rain
user netops3 password snow
exit

After you make changes to the running configuration file, you now want to roll back these changes and revert to the configuration that existed before the changes were made. The show archive command verifies the version of the configuration to be used as a replacement file. The configure replace command is then used to revert to the replacement configuration file as shown in the following example:

Device# show archive

There are currently 1 archive configurations saved.
The next archive file will be named bootflash:myconfig-2
 Archive #  Name
   0
   1       bootflash:myconfig-1 <- Most Recent
   2
   3
   4
   5
   6
   7
   8
   9
   10
Device# configure replace bootflash:myconfig-1
Total number of passes: 1
Rollback Done

Additional References

Related Documents

Related Topic Document Title

Cisco IOS commands

Cisco IOS Master Command List, All Releases

Configuration locking

"Exclusive Configuration Change Access and Access Session Locking" module in the Managing Configuration Files Configuration Guide

Commands for managing configuration files

Cisco IOS Configuration Fundamentals Command Reference

Information about managing configuration files

"Managing Configuration Files" module in the Managing Configuration Files Configuration Guide

Using the Contextual Configuration Diff Utility feature

"Contextual Configuration Diff Utility" module in the Managing Configuration Files Configuration Guide

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 Configuration Replace and Configuration Rollback

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 Configuration Replace and Configuration Rollback

Feature Name

Releases

Feature Information

Configuration Replace and Configuration Rollback

12.2(25)S

12.2(27)SBC

12.2(31)SB2

12.2(33)SB

12.2(33)SRA

12.2(33)SXH

12.3(7)T

12.3(14)T

15.0(1)EX

Cisco IOS XE Release 2.1

The Configuration Replace and Configuration Rollback feature enables you to replace the current running configuration with any saved Cisco configuration file. You can use this functionality to revert the configuration to a previous configuration state, rolling back any configuration changes that were made since that configuration file was saved.

The following commands were introduced or modified: archive config, configure confirm, configure replace, debug archive config timestamp, debug archive versioning, maximum, path (archive configuration), show archive, show configuration lock, time-period.

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R)

Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental.

© 2013 Cisco Systems, Inc. All rights reserved.