Cisco IOS XR Configuration Management: Commit, Rollback and Replace

Cisco IOS XR on ASR 9000, NCS and CRS platforms uses a commit-based configuration model that is completely different from classic IOS: changes go into a candidate configuration and only take effect when you commit them, which gives you atomic, reversible configuration changes. This article explains the model, the safety commands every engineer should use before a risky change (commit confirmed, rollback, commit replace), and the exact steps to recover when a commit breaks the box.

The Commit Model in 60 Seconds

In IOS XR, every session edits a candidate configuration. Nothing changes on the device until commit. Commits are numbered and stored as commit sets, so you can always return to a previous state:

RP/0/RSP0/CPU0:router(config)# interface GigabitEthernet0/0/0/0
RP/0/RSP0/CPU0:router(config-if)# ipv4 address 10.0.0.1 255.255.255.0
RP/0/RSP0/CPU0:router(config-if)# commit
Commit complete.

Candidate, running and the two-stage model

It helps to be precise about the three things that exist at any moment on an IOS XR box:

• Running configuration — what the router is actually using right now. It only ever changes as the result of a successful commit.
• Candidate (target) configuration — the edit buffer for your session. Configuration mode in IOS XR is locked to a single shared target by default, which is why two engineers editing at once can see each other’s work.
• Commit history — an ordered list of commit sets retained on disk. Every commit, whatever session or protocol produced it, gets a sequence number.

Because the target configuration is shared, the safest habit is to enter configuration mode, make one coherent change, commit, and exit — rather than leaving an (config) prompt open on a shared jump host for hours. A stale session with uncommitted edits will merge into somebody else’s commit unless they check the diff first.

You can also work in an isolated private target with configure private, or explicitly discard your session’s pending work with abort. Both are worth knowing: abort throws away the candidate and leaves the running configuration untouched, which is the correct response when you realise mid-edit that you are on the wrong router.

RP/0/RSP0/CPU0:router(config)# show configuration
RP/0/RSP0/CPU0:router(config)# abort
RP/0/RSP0/CPU0:router#

commit confirmed: Self-Rolling Safety Net

Before any change that could lock you out or break routing, use commit confirmed. The commit is applied, but if you do not re-commit within the timer, the router automatically rolls back:

RP/0/RSP0/CPU0:router(config)# commit confirmed 120
Commit complete.
RP/0/RSP0/CPU0:router(config)# commit
Commit complete.

If you lose connectivity, after 120 seconds the previous configuration returns automatically - the single most valuable command for remote work. A few practical rules make it safer still:

• Set the timer to roughly twice the time you realistically need to validate. 120–300 seconds covers most interface and routing changes; use 600 for a change where you must wait on a BGP convergence or a protocol timer.
• Only the second commit makes the change permanent. If you commit another edit instead of a plain commit, you restart the confirmation window rather than confirming it — easy to get wrong under pressure.
• The rollback is triggered by the router, not by your session, so it works even if you are locked out entirely. That is the whole point.

Comments, labels and knowing who changed what

Commit sets are more useful when they carry a reason. Two optional keywords make change review possible months later, in a change window at 02:00, or in front of an auditor:

RP/0/RSP0/CPU0:router(config)# commit comment "CHG0041234 - add BGP peer 10.0.0.2 to AS 65001"
RP/0/RSP0/CPU0:router(config)# commit label baseline-2026-08
RP/0/RSP0/CPU0:router(config)# show configuration commit list

Labels are searchable, which turns the commit list into a rudimentary version-control system:

RP/0/RSP0/CPU0:router# show configuration commit list label
RP/0/RSP0/CPU0:router# show configuration commit changes label baseline-2026-08
RP/0/RSP0/CPU0:router# show configuration commit changes last 5

show configuration commit changes prints the diff introduced by a commit set. Used against last 5 it answers “what changed on this box in the last few commits” in one command, without reading a 40,000-line running configuration. Get into the habit of a commit comment referencing the change ticket on every production commit.

Diffing a candidate before you commit

Reading the pending change before it goes live is the cheapest safety measure available:

RP/0/RSP0/CPU0:router(config)# show configuration
!! IOS XR Configuration 7.5.2
interface GigabitEthernet0/0/0/0
 ipv4 address 10.0.0.1 255.255.255.0
!
end

RP/0/RSP0/CPU0:router(config)# show configuration merge
RP/0/RSP0/CPU0:router(config-if)# show configuration changes diff

show configuration inside configuration mode shows only the uncommitted delta, not the whole configuration — a very different behaviour from IOS, and much easier to review. show configuration merge shows what the full running configuration would look like after the commit, which is the right view when you are adding a policy that interacts with existing statements. show configuration changes diff formats the delta as a unified diff when the output is going into a change record.

Rollback: Going Back to a Previous Commit

RP/0/RSP0/CPU0:router# show configuration commit list
1  2026-08-29 09:12:41  user  interface GigabitEthernet0/0/0/0
2  2026-08-29 09:15:03  user  BGP neighbor 10.0.0.2
3  2026-08-29 09:20:55  user  OSPF area 0
RP/0/RSP0/CPU0:router# rollback configuration commit 2
Generating configuration...
Rollback committed.

rollback configuration commit <number> reverts the running configuration to the state after that commit. You can also inspect what a rollback would change first:

show configuration rollback changes 2

Note that a rollback is itself a commit: it appears in the commit list as a new entry, it can be rolled back in turn, and it can be protected with commit confirmed if you are working remotely. The number in the list is not the number of changes — commit sets 1, 2 and 3 are sequential points in time, and any of them can be the target. On a router with thousands of commits, bound the display with show configuration commit list reverse or filter by time and user rather than paging through the lot.

commit replace: Full Configuration Replacement

When you need to load a complete new configuration (migration, config from a template), use commit replace - it atomically swaps the entire running configuration:

RP/0/RSP0/CPU0:router# configure
RP/0/RSP0/CPU0:router(config)# load /harddisk:/new-config.cfg
RP/0/RSP0/CPU0:router(config)# commit replace
Commit complete.

Anything not in the loaded configuration is removed - use commit confirmed combined with replace for safety. Two failure modes deserve their own warning:

• A truncated file. If the file transfer to /harddisk: was incomplete, commit replace will happily install a partial configuration and remove everything else. Always load /harddisk:/new-config.cfg followed by show configuration to review the loaded candidate before replacing, and verify the file size against the source.
• No management interface. Replacing a configuration that removes the interface you are managing through is the single fastest way to lose a router. Combine it with commit confirmed so the box rolls back on its own after the timer.

For partial changes, use load merge instead. It merges the file into the candidate and leaves everything else in place, which is the right tool for pushing a snippet from a template rather than a full configuration:

RP/0/RSP0/CPU0:router(config)# load merge /harddisk:/bgp-snippet.cfg
RP/0/RSP0/CPU0:router(config)# show configuration
RP/0/RSP0/CPU0:router(config)# commit

Automatic Backup and Recovery

RP/0/RSP0/CPU0:router# show configuration history
RP/0/RSP0/CPU0:router# show configuration rollback changes last 5
RP/0/RSP0/CPU0:router# config-register 0x2102

Enable commit auto-save to survive a bad commit followed by a reboot:

RP/0/RSP0/CPU0:router(config)# configuration commit auto-save
RP/0/RSP0/CPU0:router(config)# commit

If the device reboots after a bad commit, auto-save restores the last committed configuration automatically. Also configure a periodic configuration archive so that a copy of the running configuration lands on a TFTP or SCP server on a schedule:

RP/0/RSP0/CPU0:router(config)# archive
RP/0/RSP0/CPU0:router(config-archive)# time-period 1440
RP/0/RSP0/CPU0:router(config-archive)# path scp://backup@10.10.10.5/configs/

RP/0/RSP0/CPU0:router# copy running-config /harddisk:/backup-$(date).cfg
RP/0/RSP0/CPU0:router# show configuration history 5

An out-of-band copy on a server is what saves you if the router will not boot far enough to offer a rollback. Treat the archive as mandatory, not optional, on any box that carries production traffic.

Recovering when a commit locks you out

The scenario everyone fears is a commit that removes the management path — an ACL, a VRF change, a routing protocol removal — and leaves you with no reachability. Work through it in this order:

1. Wait out the commit confirmed timer if you used one. This alone resolves the majority of incidents, with no console access needed.
2. Reach the router another way. Management interfaces on separate VRFs, a serial console server, or a peer that can reach it. IOS XR keeps MgmtEth (or the /admin plane on newer chassis) separate from the forwarding configuration, so it often survives a data-plane mistake.
3. Roll back from an unaffected session: show configuration commit list, then rollback configuration commit <n-1> with commit confirmed for good measure.
4. Reboot into a known state. If a bad commit was also saved to startup configuration, boot the router and reload it. Auto-save, if enabled, restores the last committed configuration at boot.
5. Last resort — break into the boot prompt. Reboot the chassis, interrupt the boot, and use the ROMMON/Boot prompt to bypass the startup configuration and reset the config register, then load the archived configuration from your backup server.

Automating commits safely

NETCONF and gNMI both drive the same commit model, and the same safety rules apply. A typical NETCONF edit-config is not visible until the matching commit RPC; use confirmed-commit with a confirm-timeout from your automation tool so a bad push rolls back without a human. The pattern that works in production:

• Always set a commit comment containing the pipeline run ID or ticket number — without it, post-incident review is guesswork.
• Never let an automation job use commit replace unless it first reads back and diffs the running configuration.
• Snapshot the running configuration before every automated change, and keep the snapshot outside the device.

Our Ansible network modules guide covers the backup-and-diff workflow for IOS-family devices, and the same structure applies to XR with the iosxr_config module.

Best Practices

• Always commit confirmed for remote changes - set a timer longer than your expected window.
• Use show configuration commit list to keep track of what you changed.
• Keep a backup of show running-config on a server before major changes.
• Never commit a candidate you did not review - show configuration displays the pending changes.
• Write a commit comment with the change ticket on every production commit.
• Enable configuration commit auto-save and a scheduled configuration archive.
• Roll back with commit confirmed as well — a rollback that breaks something else is still an outage.
• Use load merge for snippets and reserve commit replace for genuine full-config replacement.

Common mistakes to avoid

• Leaving configuration mode open. A shared target means uncommitted edits can land inside someone else’s commit. Exit or abort when you are done.
• Assuming show configuration shows the whole config. In IOS XR, it shows the pending delta. Use show running-config for the full picture.
• Confusing commit confirmed with a permanent commit. You must commit again to confirm, and the timer keeps running until you do.
• Rolling forward instead of back. If a commit broke something, the fastest safe action is almost always a rollback to the previous commit set, not a hastily typed fix.

Related: Cisco IOS XR TAC command list, IOS XR commit replace and rollback in practice, Cisco ASR 9000 troubleshooting commands and IOS XR line card diagnostics.

原文链接：https://www.cisco.com/c/en/us/td/docs/routers/asr9000/software/asr9k-r6-4/system-management/configuration/guide/b-sysman-cg-asr9k-64x.html