Feature history for configuration replace

This table provides release and platform support information for the features explained in this module.

These features are available in all the releases subsequent to the one they were introduced in, unless noted otherwise.

Release

Feature name and description

Supported platform

Cisco IOS XE 17.18.1

Configuration replace: This feature provides the capability to automatically save copies of the running configuration to the Cisco IOS XE configuration archive.

Cisco C9350 Series Smart Switches

Cisco C9610 Series Smart Switches

Understand configuration replace

The Configuration Replace feature provides the capability to automatically save copies of the running configuration to the Cisco IOS XE configuration archive. These archived files serve as checkpoint configuration references and can be used to revert to previous configuration states. Before this feature, copies are saved in the running configuration either locally or remotely. However, this method lacked any automated file management.

Configuration archive

The Cisco IOS XE configuration archive stores, organizes, and manages configuration files. The archive config command saves Cisco IOS XE configurations in the configuration archive using a standard location and filename prefix that is automatically appended with an incremental version number (and optional timestamp) as each consecutive file is saved. This functionality provides a means for consistent identification of saved Cisco IOS XE configuration files.

You can specify the number of running configuration versions to keep in the archive. Once the archive reaches its capacity, the oldest file is deleted when the latest file is saved. The show archive command displays information for all configuration files saved in the Cisco IOS XE configuration archive.

The configuration files in the Cisco IOS XE configuration archive can be located in FTP, HTTP, RCP, and TFTP file systems.

Configuration replace

Configuration replace provides the capability to replace the current running configuration with any saved Cisco IOS XE configuration file. This functionality can be used to revert to a previous configuration state, rolling back any configuration changes that were made since the previous configuration state was saved.

When using the configure replace command, specify a saved Cisco IOS XE configuration as the replacement configuration file for the current running configuration. The replacement file must be a complete configuration generated by a Cisco IOS XE device (for example, a configuration generated by the copy running-config destination-url command), or if generated externally, the replacement file must comply with the format of files generated by Cisco IOS XE devices.

Use the configure replace command to generate differences between the current running configuration and the specified replacement configuration. The algorithm used to compare the two files is the same as using the show archive config differences command. The resulting differences are then applied by the Cisco IOS XE parser to achieve the replacement configuration state. Only the differences are applied to avoid 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 maximum of five passes is performed to preclude any looping behavior.

Configuration copy

Use the Cisco IOS XE copy source-url running-config privileged EXEC command to copy a stored Cisco IOS XE configuration file to the running configuration. When using the copy source-url running-config command as an alternative to the configure replace target-url privileged EXEC command, these major differences should be noted:

  • The copy source-url running-config command is a merge operation, preserving all 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 those that need inclusion.
  • 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 may be used as the source file for the copy source-url running-config command, whereas a complete Cisco IOS XE configuration file must be used as the replacement file for the configure replace target-url command.

Configuration lock

When the configure replace command is used, the running configuration file is locked by default 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 no lock keyword when issuing the configure replace command.

The running configuration lock is automatically cleared at the end of the configuration replace operation. Use the show configuration lock command to display current locks on the running configuration.

Configuration rollback

The Cisco IOS XE configuration rollback capability uses the concept of reverting to a specific configuration state based on a saved Cisco IOS XE configuration file, instead of basing the rollback operation on a specific set of changes that were applied. This concept is similar to the database idea of saving a checkpoint (a saved version of the database) to preserve a specific state.

The configure replace command allows you to revert to a previous configuration state, effectively rolling back changes that were made since the previous configuration state was saved. To use the configuration rollback feature, save the Cisco IOS XE running configuration before making any changes. Then, after entering configuration changes, you can use that saved configuration file to roll back the changes (using the configure replace target-url command). Furthermore, because you can specify any saved Cisco IOS XE configuration file as the replacement configuration, you are not limited to a fixed number of rollbacks, which is the case in some rollback models.

Configuration rollback confirmed change

The Configuration Rollback Confirmed Change feature allows you to make configuration changes with an optional confirmation requirement. If this confirmation is not received, the configuration is returned to its previous state. This feature safeguards against accidentally losing connectivity with a network device or management application because of configuration changes.

Contextual configuration diff utility

The Contextual Configuration Diff Utility feature provides the ability to perform a line-by-line comparison of any two configuration files (accessible through the Cisco IOS XE Integrated File System [IFS]) and generate a list of the differences between them. The generated output shows configuration lines that are added, modified, or deleted. It also indicates the configuration modes where each change occurred.

Diff operation

A diff operation is performed on the specified files and a list of differences between the two files is generated as output by using the show archive config differences command. Interpreting the output is dependent on the order in which the two files are specified in the command. Assume the file entered first is file1; the second is file2. Each entry in the generated output list is prefixed with a unique text symbol to indicate the type of difference found. The text symbols and their meanings are as follows:

  • A minus symbol (–) indicates that the configuration line exists in file1 but not in file2.
  • A plus symbol (+) indicates that the configuration line exists in file2 but not in file1.
  • An exclamation point (!) with descriptive comments identifies order-sensitive configuration lines whose location is different in file1 than in file2.

Incremental diff operation

Some applications need the output to include unmodified configuration lines (without minus and plus symbols). For these applications, an incremental diff operation can be performed by using the show archive config incremental-diffs command, which compares a specified configuration file to the running configuration file.

When an incremental diff operation is performed, a list of the configuration lines that do not appear in the running configuration file (in other words, configuration lines that appear only in the specified file being compared to the running configuration file) is generated as output. An exclamation point (!) with descriptive comments identifies order-sensitive configuration lines whose location is different in the specified configuration file than in the running configuration file.

Benefits of configuration replace

  • Reverts to a previous configuration and rolls back changes effectively.
  • Replaces 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, reducing system downtime.
  • Reverts to any saved Cisco IOS XE configuration state.
  • Simplifies configuration changes by applying a complete configuration file to the device, where only the commands that need to be added or removed are affected.
  • Increases efficiency and prevents service outages by avoiding reapplication of existing commands in the current running configuration.

Prerequisites for configuration replace

You must ensure that the format of the configuration files used as input complies with Cisco software configuration file indentation rules.

  • 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.

The software creates configuration files based on these indentation rules for commands like show running-config or copy running-config destination-url . Any configuration file generated on a Cisco device complies with these rules.

Ensure the device has free memory larger than the combined size of the current running configuration and the saved replacement configuration to perform the configuration replace operation.

Restrictions for configuration replace

  • You cannot add or remove certain Cisco configuration commands pertaining to physical components of a networking device from the running configuration. For example, if the interface FiftyGigE 1/0/1 is physically present on the device, a configuration replace operation cannot remove the command line from the current running configuration. Similarly, if no interface FiftyGigE 1/0/1 is physically present on the device, the command line cannot be added to the running configuration. These changes in a configuration replace operation cause error messages indicating failed command lines.
  • In very rare cases, you must reload the device to remove certain Cisco configuration commands from the running configuration. When a configuration replace operation attempts to remove this type of command, it results in error messages indicating failure of these specific command lines.

Configure configuration replace

This section provides the configuration tasks to perform configuration replace operations.

Create a configuration archive

Using the configure replace command in conjunction with the Cisco IOS XE configuration archive and the archive config command is optional but offers significant benefit for configuration rollback scenarios. Before using the archive config command, the configuration archive must be configured.

Perform this task to configure the characteristics of the configuration archive.

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

archive

Example:


Device(config)# archive

Enters archive configuration mode.

Step 4

path url

Example:


Device(config-archive)# path flash:myconfiguration

Specifies the location and filename prefix for the files in the Cisco IOS XE configuration archive.

 Note

If a directory is specified in the path instead of file, the directory name must be followed by a forward slash as path flash:/directory/. The forward slash is not necessary after a filename; it is only necessary when specifying a directory.

Step 5

maximum number

Example:


Device(config-archive)# maximum 14

(Optional) Sets the maximum number of archive files of the running configuration to be saved in the Cisco IOS XE configuration archive.

  • The number argument is the maximum number of archive files of the running configuration to be saved in the Cisco IOS XE configuration archive. Valid values are from 1 to 14. The default is 10.
 Note

Before using this command, configure the path command to specify the location and filename prefix for the files in the Cisco IOS XE configuration archive.

Step 6

time-period minutes

Example:


Device(config-archive)# time-period 1440

(Optional) Sets the time increment for automatically saving an archive file of the current running configuration in the Cisco IOS XE configuration archive.

  • The minutes argument specifies how often to automatically save an archive file of the current running configuration in the Cisco IOS XE configuration archive.
 Note

Before using this command, configure the path command to specify the location and filename prefix for the files in the Cisco IOS XE configuration archive.

Step 7

end

Example:


Device(config-archive)# end

Exits to privileged EXEC mode.

Step 8

archive config

Example:


Device# archive config

Saves the current running configuration file to the configuration archive.

 Note

The path command must be configured before using this command.

Perform a configuration replace or rollback

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

 Note

Create a configuration archive before performing this procedure. See Create a configuration archive for detailed steps. This procedure details how to return to that archived configuration in the event of a problem with the current running configuration.

Step 1

enable

Example:


Device> enable

Enables privileged EXEC mode.

  • Enter your password if prompted.

Step 2

configure replace target-url [nolock] [list] [force] [ignore case] [revert trigger [error] [timer minutes] | time minutes]]

Example:


Device# configure replace flash: startup-config time 120

Replaces the current running configuration file with a saved Cisco IOS XE configuration file.

  • The target-url argument is a URL (accessible by the Cisco IOS XE file system) of the saved Cisco IOS XE configuration file that is to replace the current running configuration, such as the configuration file created using the archive config command.
  • The list keyword displays a list of the command lines applied by the Cisco IOS XE software parser during each pass of the configuration replace operation. The total number of passes performed is also displayed.
  • The force keyword replaces the current running configuration file with the specified saved Cisco IOS XE configuration file without prompting you for confirmation.
  • The time minutes keyword and argument specify 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).
  • The nolock keyword disables the locking of the running configuration file that prevents other users from changing the running configuration during a configuration replace operation.
  • The revert trigger keywords set these triggers for reverting to the original configuration:
    • error : Reverts to the original configuration upon error.
    • timer minutes : Reverts to the original configuration if specified time elapses.
     Note

    In some cases, while performing the revert trigger operation for multiple pass operations, a partial configuration may be missed out causing the revert operation to the original configuration state to fail.

  • The ignore case keyword allows the configuration to ignore the case of the confirmation command.

Step 3

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

Example:


Device# configure revert now

(Optional) 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 Cisco IOS XE configuration file.

 Note

Use this command only if the time seconds keyword and argument of the configure replace command are specified.

Step 5

exit

Example:


Device# exit

Exits to user EXEC mode.

Compare files using contextual configuration diff utility

Perform this procedure to do a line-by-line file comparison using the contextual configuration diff utility.

Step 1

enable

Example:


Device> enable

Enables privileged EXEC mode.

  • Enter your password if prompted.

Step 2

Enter one of these commands:

Choose from:

  • show archive config differences [file1 [file2]]
  • show archive config incremental-diffs file

Example:


Device# show archive config differences running-config startup-config

Example:


Device# show archive config incremental-diffs nvram:startup-config

Performs a line-by-line comparison of any two configuration files (accessible through the Cisco IOS XE File System) and generates a list of the differences between them.

or

Performs a line-by-line comparison of a specified configuration file to the running configuration file and generates a list of the configuration lines that do not appear in the running configuration file.

Step 3

exit

Example:


Device# exit

Exits to user EXEC mode.

Monitor and troubleshoot

Perform this task to monitor and troubleshoot the Configuration Replace feature.

Step 1

enable

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

Example:

Device> enable

Step 2

show archive

Use this command to display information about the files saved in the Cisco IOS XE configuration archive.

Example:

Device# show archive

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

This is a 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 flash:myconfiguration-8
 Archive #  Name
   0        
   1       :Deleted
   2       :Deleted
   3       :Deleted
   4       :Deleted
   5       flash:myconfiguration-5
   6       flash:myconfiguration-6
   7       flash:myconfiguration-7 <- Most Recent
   8
   9
   10
   11
   12
   13
   14

Step 3

debug archive versioning

Use this command to enable debugging of the Cisco IOS XE configuration archive activities to help monitor and troubleshoot configuration replace and rollback.

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 flash:myconfiguration-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.

Example:

Device# debug archive config timestamp
Device# configure replace flash:myconfiguration force

Timing Debug Statistics for IOS Config Replace operation:
       Time to read file usbflash0: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.

Example:

Device# exit

Configuration examples

This section provides configuration examples of Configurarion Replace features.

Example: Create a configuration archive

This example shows how to perform the initial configuration of the Cisco IOS XE configuration archive. In this example, flash:myconfiguration is specified as the location and filename prefix for the files in the configuration archive and a value of 10 is set as the maximum number of archive files to be saved.

configure terminal
!
archive
 path flash:myconfiguration
 maximum 10
end

Example: Replace the running configuration with Cisco IOS XE configuration

This example shows how to replace the current running configuration with a saved Cisco IOS XE configuration file named flash:myconfiguration. The configure replace command interactively prompts you to confirm the operation.

Device# configure replace flash:myconfiguration

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 this example, the list keyword is specified in order to display the command lines that were applied during the configuration replace operation:

Device# configure replace flash:myconfiguration 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: Revert to the startup configuration file

This example shows how to revert to the Cisco IOS XE startup 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 flash:startup-config force

Total number of passes: 1
Rollback Done

Example: Perform a configuration replace

This example shows the use of the configure replace command with the time minutes keyword and argument. Enter the configure confirm command within the specified time limit 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).

Device# configure replace flash:startup-config time 120

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
Device# configure confirm

This example shows the use of the configure revert command with the timer keyword. Enter the configure revert command to cancel the timed rollback and trigger the rollback immediately, or to reset parameters for the timed rollback. 

Device# configure revert timer 100

Example: Perform a configuration rollback

This 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 is used to save 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, configure the path command to specify the location and filename prefix for the files in the Cisco IOS XE 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 this example:

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

After having made changes to the running configuration file, assume you now want to roll back these changes and revert to the configuration that existed before the changes were made. The show archive command is used to verify 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 this example:

Device# show archive

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

Device# configure replace flash:myconfiguration-1

Total number of passes: 1
Rollback Done

Example: Diff operation

In this example, a diff operation is performed on the running and startup configuration files. The table below shows the configuration files used for this example.

Configuration files used for the diff operation

Running configuration file

Startup configuration file 

no ip subnet-zero
ip cef
interface FastEthernet1/0
 ip address 10.7.7.7 255.0.0.0
 no ip route-cache
 no ip mroute-cache
 duplex half
no ip classless
snmp-server community public RO
 
ip subnet-zero
ip cef
ip name-server 10.4.4.4
voice dnis-map 1
 dnis 111
interface FastEthernet1/0
 no ip address
 no ip route-cache
 no ip mroute-cache
 shutdown
 duplex half
ip default-gateway 10.5.5.5
ip classless
access-list 110 deny   ip any host 10.1.1.1
access-list 110 deny   ip any host 10.1.1.2
access-list 110 deny   ip any host 10.1.1.3
snmp-server community private RW

This is a sample output from the show archive config differences command. This sample output displays the results of the diff operation performed on the configuration files. 

Device# show archive config differences system:running-config nvram:startup-config

+ip subnet-zero
+ip name-server 10.4.4.4
+voice dnis-map 1 
 +dnis 111
interface FastEthernet1/0
 +no ip address
 +shutdown
+ip default-gateway 10.5.5.5
+ip classless
+access-list 110 deny ip any host 10.1.1.1
+access-list 110 deny ip any host 10.1.1.2
+access-list 110 deny ip any host 10.1.1.3
+snmp-server community private RW
-no ip subnet-zero
interface FastEthernet1/0
 -ip address 10.7.7.7 255.0.0.0
-no ip classless
-snmp-server community public RO

Example: Incremental diff operation

In this example, an incremental diff operation is performed on the startup and running configuration files. The table below shows the configuration files used for this example.

Configuration files used for the incremental diff operation

Startup configuration file

Running configuration file 

ip subnet-zero
ip cef
ip name-server 10.4.4.4
voice dnis-map 1
 dnis 111
interface FastEthernet1/0
 no ip address
 no ip route-cache
 no ip mroute-cache
 shutdown
 duplex half
ip default-gateway 10.5.5.5
ip classless
access-list 110 deny   ip any host 10.1.1.1
access-list 110 deny   ip any host 10.1.1.2
access-list 110 deny   ip any host 10.1.1.3
snmp-server community private RW
 
no ip subnet-zero
ip cef
interface FastEthernet1/0
 ip address 10.7.7.7 255.0.0.0
 no ip route-cache
 no ip mroute-cache
 duplex half
no ip classless
snmp-server community public RO

This is a sample output from the show archive config incremental-diffs command. This sample output displays the results of the incremental diff operation performed on the configuration files. 

Device# show archive config incremental-diffs startup-config

ip subnet-zero
ip name-server 10.4.4.4
voice dnis-map 1 
 dnis 111
interface FastEthernet1/0
 no ip address
 shutdown
ip default-gateway 10.5.5.5
ip classless
 access-list 110 deny   ip any host 10.1.1.1
 access-list 110 deny   ip any host 10.1.1.2
 access-list 110 deny   ip any host 10.1.1.3
snmp-server community private RW