Configuration Replace and Configuration Rollback

The Configuration Replace and Configuration Rollback feature provides the capability to replace the current running configuration with any saved Cisco IOS configuration file. This functionality can be used to revert to a previous configuration 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.

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-configdestination-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 Archive

The Cisco IOS configuration archive is intended to provide a mechanism to store, organize, and manage an archive of Cisco IOS configuration files to enhance the configuration rollback capability provided by the
configurereplace command. Before this feature was introduced, you could save copies of the running configuration using the
copyrunning-configdestination-url command, storing the replacement file either locally or remotely. However, this method lacked any automated file management. On the other hand, the Configuration Replace and Configuration Rollback feature provides the capability to automatically save copies of the running configuration to the Cisco IOS configuration archive. These archived files serve as checkpoint configuration references and can be used by the
configurereplace command to revert to previous configuration states.

The
archiveconfig command allows you to save Cisco IOS 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 configuration files. You can specify how many versions of the running configuration are kept in the archive. After the maximum number of files are saved in the archive, the oldest file is automatically deleted when the next, most recent file is saved. The
showarchive command displays information for all configuration files saved in the Cisco IOS configuration archive.

The Cisco IOS configuration archive, in which the configuration files are stored and available for use with the
configurereplace command, can be located on the following file systems:

If your platform does not have disk0--ftp:, http:, pram:, rcp:, or tftp:

Configuration Replace

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

When using the
configurereplace
command, you must specify a saved Cisco IOS configuration as the replacement
configuration file for the current running configuration. The replacement file
must be a complete configuration generated by a Cisco IOS device (for example,
a configuration generated by the
copyrunning-configdestination-url command),
or, if generated externally, the replacement file must comply with the format
of files generated by Cisco IOS devices. When the
configurereplace command
is entered, the current running configuration is compared with the specified
replacement configuration and a set of diffs is generated. The algorithm used
to compare the two files is the same as that employed by the
showarchiveconfigdifferences
command. The resulting diffs are then applied by the Cisco IOS 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 Cisco IOS
copysource-urlrunning-config command is often used to copy a
stored Cisco IOS configuration file to the running configuration. When using
the
copysource-urlrunning-configcommand as an alternative to the
configurereplacetarget-urlcommand, the following major
differences should be noted:

The
copysource-urlrunning-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
configurereplacetarget-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
copysource-urlrunning-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
configurereplacetarget-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
copysource-urlrunning-config command, whereas a complete Cisco
IOS configuration file must be used as the replacement file for the
configurereplacetarget-url command.

In Cisco IOS Release
12.2(25)S and 12.3(14)T, a locking feature for the configuration replace
operation was introduced. When the
configurereplace 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
nolock keyword
when issuing the
configurereplacecommand.

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

Note

In a scenario when you are performing a configuration replace using a
configuration that is not sourced from IOS(such as a custom written
configuration) if the login banner has a delimiter that is not the EXT
character (ASCII code 003), the banner configuration is rejected and not
included in the replaced configuration. Non-working delimiters include ^C, %,
#, CC etc.

Configuration Rollback

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 revert 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 revert to the previous state, before any changes were applied.

The configurereplace command allows you to revert to a previous configuration 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 IOS configuration rollback capability uses the concept of reverting to a specific configuration state based on a saved Cisco IOS 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 Cisco IOS running configuration before making any configuration changes. Then, after entering configuration changes, you can use that saved configuration file to roll back the changes (using the configurereplacetarget-url
command). Furthermore, since you can specify any saved Cisco IOS 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.

Configuration Rollback Confirmed Change Operation

The Configuration Rollback Confirmed Change feature enables an added criterion of a confirmation to configuration changes. This functionality enables a rollback to occur if a confirmation of the requested changes is not received in a configured time frame. Command failures can also be configured to trigger a configuration rollback.

The following steps outline how this process is achieved:

A new option allows you to request confirmation (a confirmation time limit must be supplied) of the configuration changes.

You must enter the confirmation command. If no confirmation is entered within the requested time limit, the configuration reverts to its previous state.

Benefits of Configuration Replace and Configuration Rollback

Allows you to revert to a previous configuration 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 router or manually undo CLI changes to the running configuration file, therefore reducing system downtime.

Allows you to revert to any saved Cisco IOS configuration state.

Simplifies configuration changes by allowing you to apply a complete configuration file to the router, where only the commands that need to be added or removed are affected.

When using the
configurereplace command as an alternative to the
copysource-urlrunning-config command, 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

Creating a Configuration
Archive

No prerequisite
configuration is needed to use the
configurereplace
command. Using the
configurereplace command
in conjunction with the Cisco IOS configuration archive and the
archiveconfig command
is optional but offers significant benefit for configuration rollback
scenarios. Before using the
archiveconfig command,
the configuration archive must be configured. Perform this task to configure
the characteristics of the configuration archive.

SUMMARY STEPS

1.enable

2.configureterminal

3.archive

4.pathurl

5.maximumnumber

6.time-periodminutes

7.end

8.archiveconfig

DETAILED STEPS

Command or Action

Purpose

Step 1

enable

Example:

Device> enable

Enables
privileged EXEC mode.

Enter your
password if prompted.

Step 2

configureterminal

Example:

Device# configure terminal

Enters global
configuration mode.

Step 3

archive

Example:

Device(config)# archive

Enters archive
configuration mode.

Step 4

pathurl

Example:

Device(config-archive)# path flash:myconfig

Specifies the
location and filename prefix for the files in the Cisco IOS 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 follows: path flash:/directory/. The forward
slash is not necessary after a filename; it is only necessary when specifying a
directory.

Step 5

maximumnumber

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 configuration archive.

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

Note

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

Step 6

time-periodminutes

Example:

Device(config-archive)# time-period 10

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

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

Note

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

Step 7

end

Example:

Device(config-archive)# end

Exits to
privileged EXEC mode.

Step 8

archiveconfig

Example:

Device# archive config

Saves the
current running configuration file to the configuration archive.

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

Note

You must create a
configuration archive before performing this procedure. See Creating a
Configuration Archive for detailed steps. The following procedure details how
to return to that archived configuration in the event of a problem with the
current running configuration.

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

The
target
-url argument is
a URL (accessible by the Cisco IOS file system) of the saved Cisco IOS
configuration file that is to replace the current running configuration, such
as the configuration file created using the
archiveconfig command.

The
list keyword
displays a list of the command lines applied by the Cisco IOS software parser
during each pass of the configuration replace operation. The total number of
passes performed is also displayed.

The
forcekeyword
replaces the current running configuration file with the specified saved Cisco
IOS configuration file without prompting you for confirmation.

The
timeminuteskeyword and argument specify the time (in
minutes) within which you must enter the
configureconfirm command
to confirm replacement of the current running configuration file. If the
configureconfirm 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
configurereplace
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
reverttrigger
keywords set the following triggers for reverting to the original
configuration:

error--Reverts to the original configuration upon
error.

timerminutes--Reverts to the original configuration if
specified time elapses.

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

Step 3

configurerevert{now|timer{minutes|idleminutes}}

Example:

Device# configure revert now

Example:

(Optional) To
cancel the timed rollback and trigger the rollback immediately, or to reset
parameters for the timed rollback, use the
configurerevertcommand in privileged EXEC mode.

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

configureconfirm

Example:

Device# configure confirm

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

Note

Use this
command only if the
timeseconds keyword and argument of the
configurereplace command are specified.

Step 5

exit

Example:

Device# exit

Exits to user
EXEC mode.

Monitoring and
Troubleshooting the Feature

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

SUMMARY STEPS

1.enable

2.showarchive

3.debugarchiveversioning

4.debugarchiveconfigtimestamp

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

showarchive

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

The following
is sample output from the
showarchive 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.

Creating a Configuration
Archive Example

The following
example shows how to perform the initial configuration of the Cisco IOS
configuration archive. In this example, flash:myconfig 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:myconfig
maximum 10
end

Replacing the Current Running
Configuration with a Saved Cisco IOS Configuration File Example

The following
example shows how to replace the current running configuration with a saved
Cisco IOS configuration file named flash:myconfig. The
configurereplace command interactively prompts you to
confirm the operation.

Device# configure replace flash: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 flash: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

Reverting to the Startup
Configuration File Example

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

The following example shows the use of the
configure replace command with the
timeminutes keyword and argument. You must 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 nvram: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

The following example shows the use of the
configure revert command with the
timer keyword. You must 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

Performing a Configuration
Rollback Operation Example

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
archiveconfig command
is used to save the current running configuration. The generated output of the
configurereplace command
indicates that only one pass was performed to complete the rollback operation.

Note

Before using the
archiveconfig command,
you must configure the
path command to
specify the location and filename prefix for the files in the Cisco IOS
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:

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
showarchive command
is used to verify the version of the configuration to be used as a replacement
file. The
configurereplace command
is then used to revert to the replacement configuration file as shown in the
following example:

RFCs

No new or modified RFCs are supported by this feature, and support for existing RFCs has not been modified by this feature.

--

Technical Assistance

Description

Link

The Cisco Support website provides extensive online resources, including documentation and tools for troubleshooting and resolving technical issues with Cisco products and technologies.

To receive security and technical information about your products, you can subscribe to various services, such as the Product Alert Tool (accessed from Field Notices), the Cisco Technical Services Newsletter, and Really Simple Syndication (RSS) Feeds.

Access to most tools on the Cisco Support website requires a Cisco.com user ID and password.

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
.
An account on Cisco.com is not required.

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

In Cisco IOS XE Release 3.6E, this feature
is supported on Cisco Catalyst 3850 Series Switches.

The
Configuration Versioning feature allows you to maintain and manage backup
copies of the Cisco IOS running configuration on or off the device. The
Configuration Replace feature uses the Configuration Versioning feature to
provide a rollback to a saved copy of the running configuration.

In Cisco IOS XE Release 3.6E, this feature is supported on
Cisco Catalyst 3850 Series Switches.

Exclusive
Configuration Change Access

Cisco IOS XE Release 3.6E

The
Exclusive Configuration Change Access feature (also called the Configuration
Lock feature) allows you to have exclusive change access to the Cisco IOS
running configuration, preventing multiple users from making concurrent
configuration changes.

The
following command was modified by this feature and applies to the Configuration
Replace and Configuration Rollback feature:
showconfigurationlock.

In Cisco IOS XE Release 3.6E, this feature is supported on
Cisco Catalyst 3850 Series Switches.