Cisco Nexus NX-OS Checkpoint and Rollback Guide

NX-OS does not keep an IOS-XR-style commit history, so on Nexus switches the equivalent safety net is the checkpoint and rollback feature: you snapshot the running configuration to a named checkpoint, make your changes, and if something breaks you roll the running configuration back to that snapshot. NX-OS even creates system checkpoints automatically when you disable a feature or remove a protocol instance. This guide covers creating checkpoints on Nexus 9000 and 3000 series, previewing the change with a diff, and executing atomic and best-effort rollbacks. It also explains how to manage checkpoints over time, how to verify a rollback actually landed, and a repeatable maintenance workflow that turns a risky change into a reversible one.

How NX-OS Checkpoints Work

A checkpoint stores the full running configuration. You can keep up to ten named checkpoints per switch; each is synchronized to the standby supervisor and survives reloads - but a write erase followed by reload deletes them, and they are local to the switch (you cannot apply one switch's checkpoint to another).

User Checkpoints vs System Checkpoints

Every checkpoint is one of two kinds. A user checkpoint is the one you create deliberately to mark a known-good state; its name is the only handle you will use during a rollback. A system checkpoint is created automatically by the switch, and NX-OS does this whenever the effect of a configuration change is not fully reversible — disabling a feature, removing a routing protocol instance, or deleting a VDC. System checkpoints are named with a fixed prefix and carry a description naming the event that created them, which makes them valuable when you need to reverse an action you took maybe minutes ago and did not anticipate. Because they are generated by the system, you cannot create them by hand and they are removed automatically when they are no longer relevant. When planning a change, always create an explicit user checkpoint: the system ones appear only after the risky command has already been issued.

Creating a Checkpoint

switch# checkpoint stable
switch# checkpoint before-ospf-change description "pre-OSPF maintenance"

Name one anything up to 80 characters; unnamed checkpoints become user-checkpoint-1 through -10.

Managing and Comparing Checkpoints

Checkpoints accumulate, and you only get ten. Before creating a new one, look at what is already there so you do not burn a slot on a stale snapshot:

switch# show checkpoint summary
switch# show checkpoint detail stable
switch# delete checkpoint old-baseline
switch# checkpoint stable description "post-upgrade baseline"

Unlike creating a checkpoint, deleting an existing one frees its name for reuse. A workable housekeeping convention is to keep one long-lived baseline per switch and rotate one or two dated checkpoints around it, deleting the oldest each time you take a fresh one.

Previewing the Rollback with a Diff

Before committing to a rollback, compare the checkpoint with the current running configuration. This shows exactly what the rollback will add, remove or change:

switch# show diff rollback-patch checkpoint stable running-config
switch# show checkpoint stable
switch# show checkpoint summary

The diff output is a patch: lines marked for addition are the commands a rollback will re-apply, and lines marked for removal are the commands the rollback will take out. Read it every time — a checkpoint taken after an unrelated mistake will faithfully restore that mistake along with everything else, and the diff is the only place you will see it before it happens. If the intended change is small but the diff is enormous, the checkpoint is not the right one and you should reconsider.

Rolling Back the Running Configuration

switch# rollback running-config checkpoint stable atomic

Atomic rollback (the default) applies the whole rollback only if no errors occur - if any command fails, the configuration is left unchanged. For recoveries where you accept partial application, use best-effort mode:

switch# rollback running-config checkpoint stable best-effort

During an atomic rollback do not make other configuration changes on the switch or from another session; a concurrent change causes the rollback to fail.

Atomic vs Best-Effort Rollback: Which to Choose

The two modes answer different questions. An atomic rollback asks "either the whole snapshot is restored or nothing at all" — the switch validates the entire patch before it commits, so a single failing command leaves the configuration exactly as it was. That all-or-nothing property is what you want in a planned reversal: if it does not succeed, your current configuration is still intact and you can investigate. A best-effort rollback asks "restore as much as possible" — NX-OS applies every command it can and reports the ones that failed, which is the pragmatic choice when the switch is already broken and you need to get as close to a known-good state as the hardware and licences will allow. The cost is that you end up in a partially restored state and must read the output carefully to find out which parts did not apply.

Verifying the Rollback

A rollback is not finished when the prompt returns. Confirm it applied, then make it permanent:

switch# show rollback log verify
switch# show rollback status
switch# show diff rollback-patch running-config checkpoint stable
switch# copy running-config startup-config

The verify command reports whether the running configuration now matches the checkpoint. The final copy running-config startup-config is essential: a rollback changes only the running configuration, and a reload before saving would come back up in the broken state you just repaired. The last diff, run in the opposite direction, should be empty when the rollback succeeded completely.

Guidelines and Limitations

• Only one checkpoint, rollback or copy running-config to startup-config operation may run at a time.
• Checkpoint names must be unique; you cannot overwrite an existing checkpoint of the same name.
• Rollback is not supported for auto-configurations or across software versions.
• Verify the result and save it: after a rollback, copy the running configuration to startup so the recovered state survives a reload.

switch# show rollback log verify
switch# copy running-config startup-config

A Safe Configuration Change Workflow

1. Capture the baseline. Create a named checkpoint with a description that says what it represents: checkpoint pre-change-2026-05 description "before BGP policy edit".
2. Make the change. Apply the configuration, one logical block at a time, so you know which block caused a problem if one appears.
3. Validate the running state. Check that the intended features came up — routing adjacencies, interface states, feature licences — before you trust the change.
4. Save if healthy. copy running-config startup-config, and take a fresh post-change checkpoint so the next maintenance window has an accurate starting point.
5. Roll back if not. Diff against the pre-change checkpoint, read the patch, roll back, verify with show rollback log verify, and save.
6. Clean up. Delete superseded checkpoints so you keep slots free for the next window.

The discipline is simple: never change a Nexus switch without a checkpoint taken in the same session, and never leave a rollback unsaved. Together those two habits make a fatal typo a five-minute event instead of an outage.

What a Checkpoint Captures — and What It Does Not

A checkpoint stores the running configuration, and a rollback restores the running configuration. That scope is precise, and misunderstanding it is the root of most failed recoveries. Features that live outside the running configuration are not touched: installed licences, bootflash images and their boot variables, the contents of the file system, and the startup configuration on the supervisor all stay exactly as they are. Operational state is also out of scope — interfaces renegotiate, routing protocols re-converge, ARP and MAC tables repopulate, and any traffic that depended on the state you just removed is disrupted for as long as reconvergence takes. A rollback is therefore a configuration operation with real service impact, not an undo button for the last five minutes of the network's life. Plan for the reconvergence, and never run a rollback on a switch you cannot afford to disturb during business hours.

Rollback in a vPC Environment

On a vPC pair, the peer link, the vPC domain and the member port-channel configurations all sit inside the running configuration, so a rollback that changes any of them can break the peer relationship and trigger a vPC consistency check failure. Two rules keep this manageable. First, roll back one switch at a time and never both members in the same window — with the peer link down, both switches fall back to their own forwarding decisions and can create the very loops you are trying to avoid. Second, after the rollback completes and the configuration is saved, verify the pair is healthy again:

switch# show vpc
switch# show vpc consistency-parameters global
switch# show vpc peer-keepalive

If the vPC domain does not come back consistently, the safest recovery is usually to bring the two switches into line deliberately rather than to attempt a second rollback on top of the first.

Common Mistakes

• Rolling back without saving afterwards. The running configuration looks right, then the switch reloads overnight and returns to the broken state. Always follow a rollback with copy running-config startup-config.
• Using the wrong checkpoint. Ten named snapshots accumulate quickly; always confirm the name and read the diff before rolling back, because a stale checkpoint restores stale mistakes.
• Rolling back concurrent changes. A rollback reverts the whole configuration, not just your change, so any other engineer's edit made since the checkpoint is wiped out too. Coordinate the window and make it exclusive.
• Ignoring the failure output. A best-effort rollback reports the commands that did not apply; skipping that output leaves you in a partially restored state you do not understand.
• Expecting rollback to cover everything. Checkpoints do not protect against a bad software upgrade, a licence change or a hardware fault — those need a different plan.

Related Articles

Related articles: Cisco Nexus NX-OS VLAN trunk configuration, Nexus vPC failover troubleshooting, and Arista EOS configuration session rollback.

原文链接：https://www.cisco.com/c/en/us/td/docs/switches/datacenter/nexus9000/sw/93x/system-management/b-cisco-nexus-9000-series-nx-os-system-management-configuration-guide-93x/b-cisco-nexus-9000-series-nx-os-system-management-configuration-guide-93x_chapter_011001.html