Controller Configuration Backup, Restore, and Rollback

Updated: April 15, 2026

Want to summarize with AI?

Describes the features for creating configuration snapshots, restoring saved configurations, and returning controller configuration to a previous state.

Controller configuration management provides the following methods for preserving or recovering configuration state:

A backup creates a snapshot of the controller configuration.
A restore applies a previously saved configuration.
A rollback returns the controller configuration to a previous state.

Configuration Backup, Restore, and Rollback Job Workflow

Configuration backup, restore, and rollback operations run as jobs that are associated with their policies.

After you configure a policy, set adminSt to triggered to start the job.
The triggered job creates a configJob object under a configJobCont container. The policy DN is the naming property.
The lastJobName property of the container identifies the most recent job for the policy.

`configJob` Fields and Values

The following fields describe the execution and status of a configuration job:

Table 1. `configJob` Fields
Field	Description
Execution time	Indicates when the job runs.
File name	Identifies the file that the job processes or generates.
Status	Indicates the current job state: `Pending`, `Running`, `Failed`, `Fail-no-data`, `Success`, or `Success-with-warnings`.
Details	Provides failure messages and warnings.
Progress	Reports the completion percentage as `100 * lastStepIndex / totalStepCount`.
`lastStepDescr`	Describes the most recently executed job action.

Note

A configJobCont container retains up to five configJob objects. When a new job exceeds this limit, the system removes the oldest job.

fileRemotePath Object

The fileRemotePath managed object defines a remote directory that file import and export operations can access.

Remote Location Parameters

The following parameters define the connection to the remote location:

Table 2. `fileRemotePath` Parameters
Parameter	Description
Hostname or IP address	Identifies the remote host.
Port	Specifies the network port on the remote host.
Protocol	Specifies a supported transfer protocol, such as FTP or SCP.
Remote directory	Specifies a directory on the remote host, not a file path.
Username	Specifies the username for authenticating to the remote host.
Password	Specifies the password for authenticating to the remote host.

Resubmit the password whenever you modify the fileRemotePath object.

fileRemotePath Configuration example

Under the fabricInst object (uni/fabric), enter a configuration similar to the following example:

<fileRemotePath name="path-name" host="host-name-or-IP-address" protocol="scp"
				remotePath="path/to/some/folder" userName="user-name" userpasswd="password"/>

Configuration Exports to a Controller or Remote Location

A configuration export policy extracts user-configurable managed-object trees from all cluster shards and creates a compressed archive.

The configExportP object defines the export policy.
A local export creates a snapshot on the controller. The configSnapshot object contains information about the snapshot.
A remote export uses the configRsRemotePath relation to reference a fileRemotePath object.
You can trigger an export immediately or associate the policy with a scheduler.

Configuration Export Policy Attributes

The following attributes define the content and destination of an export:

Table 3. `configExportP` Attributes
Attribute	Description
`name`	Specifies the policy name.
`format`	Specifies whether data in the archive uses XML or JSON format.
`targetDn`	Specifies the DN of the object to export. An empty value exports the complete configuration.
`snapshot`	When set to `true`, stores the archive on the controller and ignores any configured remote path.
`includeSecureFields`	Specifies whether the export includes encrypted secure fields, such as passwords. The default value is `true`.

To schedule exports, use the configRsExportScheduler relation to associate the export policy with a trigSchedP object. The scheduler is optional. To trigger a policy manually, set adminSt to triggered.

Note

If an archive cannot be uploaded to a remote location, see Connectivity Issues.

NX-OS-Style CLI Export Example

The following example creates an XML export policy without a remote path, selects the export target, triggers the export, and lists the locally stored archive:

apic1(config)# snapshot export policy-name
				apic1(config-export)# format xml
				apic1(config-export)# no remote path
				apic1(config-export)# target
				WORD  infra, fabric or tenant-x
				apic1(config-export)# exit
				apic1# trigger snapshot export policy-name
				apic1# ls /data2
				ce_Dailybackup.tgz

If you do not configure a remote path, the controller stores the export archive in /data2. If you do not specify a target, the policy exports the complete configuration.

GUI Export Example

On the menu bar, choose Admin > IMPORT/EXPORT.
Under Export Policies, click Configuration.
Click the export policy to use, for example, defaultOneTime.
For Format, choose XML or JSON.
For Start Now, choose Yes to run the export immediately or No to use a schedule.
In the Target DN field, enter the DN of the configuration object to export. Leave the field empty to export the complete configuration.
Select Snapshot to store the archive on the controller. Clear Snapshot to use a remote location.
To schedule the export, configure the Scheduler field.
In the Encryption field, specify whether to encrypt secure configuration properties.
Click Submit.

REST API Export Example

The following example creates and triggers a remote XML export with an optional scheduler:

<configExportP name="policy-name" format="xml" targetDn="/some/dn"
				snapshot="false" adminSt="triggered">
				<configRsRemotePath tnFileRemotePathName="remote-path-name"/>
				<configRsExportScheduler tnTrigSchedPName="scheduler-name"/>
				</configExportP>

Configuration Imports to a Controller

A configuration import retrieves and extracts an exported archive, parses and analyzes its contents, and applies the configuration to the controller one shard at a time.

The configImportP object defines the import policy.
An import can merge the archived configuration with the current configuration or replace the current configuration.
The import mode determines whether an error affects an individual managed object or an entire shard.
The source can be a snapshot on the controller or an archive at a configured remote location.

Configuration Import Policy Attributes

The following attributes define the source and behavior of a configuration import:

Table 4. `configImportP` Attributes
Attribute	Description
`name`	Specifies the policy name.
`fileName`	Specifies the name of the configuration archive to import.
`importMode`	Specifies how the import handles errors. The `best-effort` mode applies each managed object individually and skips invalid managed objects. The `atomic` mode applies the configuration by shard and rolls back a shard if an error occurs.
`importType`	Specifies whether the import merges the archive with the current configuration or replaces the current configuration. The `replace` value is supported only with atomic mode.
`snapshot`	When set to `true`, imports an archive stored on the controller and ignores the remote-path configuration.
`failOnDecryptErrors`	When set to `true`, stops the import if the encryption key for the archive does not match the system key.

For a remote import, the configRsRemotePath relation references the fileRemotePath object. The controller applies the archive in the following shard order:

infra
fabric
tn-common
All remaining shards

Configuration Import Troubleshooting

Use the following information to troubleshoot configuration import failures and warnings:

Table 5. Configuration Import Issues
Issue	Action or Result
The controller cannot download the archive.	Verify connectivity to the remote location and confirm the remote-path configuration.
The import completes with warnings.	Review the import-job details for the affected managed objects and warning messages.
The controller cannot parse the archive.	Verify that the XML or JSON is valid and that the archive was not modified manually.
The import reports an unknown property.	Check for software-model differences between the source and destination systems and for manual changes to the archive.
A configuration error occurs in best-effort mode.	The controller skips the invalid managed object and continues the import.
A configuration error occurs in atomic mode.	The controller rolls back the affected shard and continues according to the import-job result.

NX-OS-Style CLI Import Example

The following example creates a snapshot import policy, selects an archive, and triggers the import:

apic1# configure
				apic1(config)# snapshot
				apic1(config)# snapshot import
				apic1(config)# snapshot import policy-name
				apic1(config-import)# action merge
				apic1(config-import)# file archive-name
				apic1(config-import)# no remote path
				apic1(config-import)# exit
				apic1# trigger snapshot import policy-name

Use show snapshot files to identify an archive that is stored on the controller. For the import action, specify merge or replace.

GUI Import Example

On the menu bar, choose Admin > IMPORT/EXPORT.
Under Import Policies, click Configuration.
Click Create Configuration Import Policy.
Enter a policy name and select the configuration archive.
For Import Type, choose Merge or Replace.
For Import Mode, choose Best Effort or Atomic. To restore the fabric to a known configuration state, choose Replace and Atomic.
Select Snapshot to import an archive from the controller. Clear Snapshot to import an archive from a remote location.
If you cleared Snapshot, select the configured remote location in the Import Source field.
Configure the encryption option as required and click Submit.

REST API Import Example

The following example creates and triggers an atomic replacement import from a remote archive:

<configImportP name="policy-name" fileName="someexportfile.tgz"
				importMode="atomic" importType="replace" snapshot="false"
				adminSt="triggered">
				<configRsRemotePath
				tnFileRemotePathName="remote-path-name"/>
				</configImportP>

Configuration Snapshots

A configuration snapshot is a backup archive that the controller stores in a controller-managed folder and replicates across the controller cluster.

An export policy creates a snapshot when the snapshot property is set to true.
A snapshot export does not require a remote-path configuration.
The configSnapshot managed object exposes information about a snapshot.
You can create a snapshot immediately or use a scheduled export policy to create recurring snapshots.

Configuration Snapshot Attributes

The following configSnapshot attributes identify and manage a snapshot:

Table 6. `configSnapshot` Attributes
Attribute	Description
File name	Identifies the snapshot archive.
File size	Specifies the size of the snapshot archive.
Creation date	Specifies when the controller created the snapshot.
Root DN	Identifies the configuration included in the snapshot, such as the fabric, infrastructure, or a specific tenant.
`retire`	When set to `true`, removes the snapshot.

Creating and Importing Snapshots in the GUI

Use the following locations in the GUI to manage configuration snapshots:

To view the policy for recurring snapshots, choose Admin > Import/Export > Export Policies > Configuration > defaultAuto.
To import a snapshot, choose Admin > Import/Export > Import Policies. Right-click Import Policies, choose Create Configuration Import Policy, and configure the import-policy attributes.

Configuration Snapshot Manager Policy

The configSnapshotManagerP policy manages the transfer of configuration snapshot archives between a controller and a configured remote location.

Upload mode transfers a snapshot from the controller to a remote location.
Download mode transfers a remotely stored export archive to the controller as a snapshot.
The configRsRemotePath relation identifies the remote location for the transfer.
You can manage snapshot transfers by using the NX-OS-style CLI, GUI, or REST API.

Snapshot Manager Policy Behavior

The snapshot manager policy requires a policy name, a snapshot file name, a transfer mode, and a remote-path relation. To run the transfer, set the adminSt property to triggered.

Note

Recurring snapshots are available at Admin > Import/Export > Export Policies > Configuration > defaultAuto.

NX-OS-Style CLI Snapshot Transfer Example

The following example uploads a snapshot from the controller to a remote location:

apic1(config)# snapshot upload policy-name
				apic1(config-upload)# file snapshot-file-name
				apic1(config-upload)# remote path remote-path-name
				apic1(config-upload)# exit
				apic1# trigger snapshot upload policy-name

Use show snapshot files to identify a snapshot file on the controller.

apic1(config)# snapshot download policy-name
				apic1(config-download)# file remote-file-name
				apic1(config-download)# remote path remote-path-name
				apic1(config-download)# exit
				apic1# trigger snapshot download policy-name

GUI Snapshot Transfer Example

To upload a snapshot to a remote location, complete the following actions:

In the Config Rollbacks pane, right-click the snapshot file and choose Upload to Remote Location.

The Upload Snapshot to Remote Location dialog box appears.
Configure the remote-location information, and click Submit.

To download a remotely stored export archive as a snapshot, complete the following actions:

Click the Import icon.

The Import Remotely Stored Export Archive to Snapshot dialog box appears.
In the File Name field, enter the name of the remote archive.
From the Import Source drop-down list, choose a remote location. To configure a remote location, select Or create a new one.
Click Submit.

REST API Snapshot Transfer Example

The following example creates and triggers a snapshot upload or download policy:

<configSnapshotManagerP name="policy-name"
				fileName="snapshot-file-name" mode="upload|download"
				adminSt="triggered">
				<configRsRemotePath
				tnFileRemotePathName="remote-path-name"/>
				</configSnapshotManagerP>

Configuration Rollback

The configRollbackP policy compares two configuration snapshots and reverses the changes that occurred between them.

The rollback recreates managed objects that were deleted between the first and second snapshots.
The rollback deletes managed objects that were created between the snapshots if they and their descendants were not modified after the second snapshot.
The rollback restores previous property values for managed objects that were modified between the snapshots, unless they were modified after the second snapshot.
Preview mode generates a differences file without changing the configuration.

Configuration Rollback Behavior

A rollback operates only on snapshots. It does not require a remote-path configuration and ignores any remote path that is specified. To use a remote archive, first download the archive as a snapshot by using the configSnapshotManagerP policy. For more information, see Configuration Snapshot Manager Policy.

Set snapshotOneDn to the DN of the earlier snapshot and snapshotTwoDn to the DN of the later snapshot. The following table describes how the policy handles differences between the snapshots:

Table 7. Configuration Rollback Actions
Difference	Rollback Action	Condition
A managed object exists in the first snapshot but not in the second snapshot.	Recreates the managed object.	The managed object was deleted between the snapshots.
A managed object does not exist in the first snapshot but exists in the second snapshot.	Deletes the managed object.	Neither the managed object nor its descendants were modified after the second snapshot.
A managed object exists in both snapshots with different property values.	Restores the property values from the first snapshot.	The managed object was not modified after the second snapshot.

Configuration Difference Files

Each rollback job generates a differences file that describes the configuration changes. Retrieve the file through the REST API at apichost/mqapi2/snapshots.readiff.xml?jobdn=SNAPSHOT_JOB_DN.

To compare two snapshots without configuring a rollback policy, use apichost/mqapi2/snapshots.diff.xml?s1dn=SNAPSHOT_ONE_DN&s2dn=SNAPSHOT_TWO_DN.

NX-OS-Style CLI Rollback Example

The following example selects two snapshots, enables preview mode, and triggers a rollback policy:

apic1# show snapshot files
				File    : ce2_DailyAutoBackup-2015-11-21T01-00-17.tar.gz
				Created : 2015-11-21T01:00:21.167+00:00
				Size    : 22926
				File    : ce2_DailyAutoBackup-2015-11-21T09-00-21.tar.gz
				Created : 2015-11-21T09:00:24.025+00:00
				Size    : 23588
				apic1# configure
				apic1(config)# snapshot rollback myRollbackPolicy
				apic1(config-rollback)# first-file ce2_DailyAutoBackup-2015-11-21T01-00-17.tar.gz
				apic1(config-rollback)# second-file ce2_DailyAutoBackup-2015-11-21T09-00-21.tar.gz
				apic1(config-rollback)# preview
				apic1(config-rollback)# end
				apic1# trigger snapshot rollback myRollbackPolicy

GUI Snapshot Comparison Example

On the menu bar, click Admin.
Click Config Rollbacks.
In the left pane, select the first snapshot from the Config Rollbacks list.
In the Configuration for Selected Snapshot pane, select the configuration to compare.
From the Compare with Previous Snapshot drop-down list, select the second snapshot.

The controller generates a differences file for the two snapshots.

REST API Rollback Example

The following example creates and triggers a rollback policy:

<configRollbackP name="policy-name"
				snapshotOneDn="dn/of/snapshot/one"
				snapshotTwoDn="dn/of/snapshot/two"
				preview="no" adminSt="triggered"/>

Need help?

Open a support case

(Requires a Cisco Service Contract)

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.