IOS XR Preconfigured Interfaces and commit best-effort

2026年9月21日 LOG admin

Interface preconfiguration lets you type the entire interface stanza for a line card that is not installed yet, commit it, and have it take effect the moment the hardware appears. On IOS XR this is not a cosmetic feature — it is how you keep a change window short when new cards arrive at 2 a.m., and how you keep configuration in Git ahead of hardware in an automated build. The catch is that it depends on commit best-effort semantics, which behave differently from a normal commit. This article covers the workflow, what best-effort actually commits, and the verification that proves the preconfiguration landed.

Why preconfigure instead of configuring on arrival

Shorter change windows — the card boots into a completed configuration instead of a half-applied one.
Configuration as code — interface stanzas can be reviewed and stored before the hardware exists.
Fewer typos under pressure — the same template you tested elsewhere is applied verbatim.
Predictable bring-up — when the card comes up, the verifiers registered for the preconfigured interfaces validate the state automatically.

The preconfiguration workflow

RP/0/RP0/CPU0:router# configure
RP/0/RP0/CPU0:router(config)# interface preconfigure HundredGigE0/0/0/0
RP/0/RP0/CPU0:router(config-if-pre)# description PRECONFIG-NEW-LINECARD
RP/0/RP0/CPU0:router(config-if-pre)# mtu 9216
RP/0/RP0/CPU0:router(config-if-pre)# ipv4 address 192.168.1.2/31
RP/0/RP0/CPU0:router(config-if-pre)# load-interval 30
RP/0/RP0/CPU0:router(config-if-pre)# no shutdown
RP/0/RP0/CPU0:router(config-if-pre)# commit best-effort

Two things are unusual here. First, the mode prompt is (config-if-pre), not (config-if): you are editing a preconfiguration that will be attached to hardware later. Second, you must commit with commit best-effort — a plain commit may be rejected because the interface does not exist in the IM database yet.

What commit best-effort really does

A normal IOS XR commit is atomic: either every line is valid and the whole change lands, or the commit fails and the running configuration is untouched. commit best-effort relaxes that guarantee. It merges the target configuration into the running configuration and commits only the parts that are semantically valid; invalid parts fail silently while the valid ones take effect.

Command	Behaviour	Typical use
`commit`	All-or-nothing; failure leaves the running config unchanged	Production changes
`commit best-effort`	Valid changes land, invalid ones fail	Preconfiguration, partially available hardware
`commit replace`	Replaces the running configuration wholesale	Bootstrapping, restore from template
`end`	Exits the session and commits	Routine edits
`abort`	Discards the session without committing	Backing out of a risky change

Best-effort is convenient and dangerous in equal measure. Nothing in the CLI output tells you which lines were dropped; you have to read back the configuration. That is why the verification step below is mandatory rather than optional.

Verifying the preconfiguration

RP/0/RP0/CPU0:router# show running-config interface preconfigure HundredGigE0/0/0/0
RP/0/RP0/CPU0:router# show running-config interface HundredGigE0/0/0/0
RP/0/RP0/CPU0:router# show configuration failed

show configuration failed is the most important of the three: after a best-effort commit it lists the lines that did not take effect, which is the only reliable way to detect a partially applied stanza. Run it every time, even when the commit prompt looked clean.

When the card arrives

Once the line card is physically installed and the interfaces appear in the IM database, the preconfiguration is matched against the installed hardware. Interfaces that match existing definitions come up with the preconfigured parameters; you then commit normally to make the state permanent. If you preconfigured an interface type the card does not support, the stanza stays in the running configuration unevaluated — harmless but a trap for audits, because your running configuration contains interfaces that do not exist.

Operational pitfalls

Version dependencies — the exact preconfigure syntax and the interface definition file requirement differ by IOS XR release; check the guide for your version before scripting it.
Preconfiguring both RPs — the preconfiguration must be present on the standby as well, or a switchover loses it.
Config diff tooling — many diff tools mark preconfigure stanzas as missing from the device, generating false alerts; exclude them or normalise the output.
Combining with replace — a later commit replace can silently remove preconfigurations that are not in the replacement file.
Management reachability — for a management Ethernet pairing across two RPs, both ports must be physically connected to the same switch or LAN segment or switchover is not transparent.

A repeatable bring-up procedure

Generate the interface stanzas from your template tooling and load them into a configuration session.
Apply with commit best-effort.
Run show configuration failed and fail the change if anything is listed.
Confirm the preconfigured interfaces exist with show running-config interface preconfigure.
Install the card; watch the bring-up and confirm the interfaces inherit the preconfigured addressing, MTU and description.
Commit normally and back up the running configuration.

Using preconfiguration in a pipeline

The biggest operational win from preconfiguration comes from treating interface stanzas as generated artefacts rather than hand-typed configuration. A workable pipeline:

Source of truth — a YAML or CSV inventory describing each device, slot, port, description, MTU and addressing.
Renderer — a template (Jinja2 is the usual choice) that emits IOS XR syntax for one interface or the whole device.
Artifact — the rendered configuration is committed to the repository, so the review happens on the file rather than on a terminal session.
Delivery — an Ansible task or a scripted CLI session loads the file and preconfigures the interfaces.
Verification — the pipeline reads back the preconfigured interfaces and fails the job if the intended state is not present.

Two details keep this safe. First, always generate and deliver interface descriptions that identify the change ticket — three months later that string is the fastest way to know why a port exists. Second, keep the renderer's variables flat enough that a missing value causes a hard failure rather than an empty address; a template that silently emits an interface with no address is worse than no template at all.

Failure case: the card arrives and interfaces stay down

The most common disappointment with preconfiguration is a card that installs cleanly while its interfaces remain administratively down or unconfigured. Work through this list:

Symptom	Likely cause	Confirmation
Interface exists but has no configuration	The preconfigured interface name does not match the installed hardware's naming	`show running-config interface preconfigure` versus `show interfaces brief`
Configuration present but interface shut	Preconfiguration carried `shutdown` implicitly or explicitly	`show running-config interface <name>`
Best-effort commit dropped lines	Syntax valid only on a later IOS XR release, or a feature not supported on that line card	`show configuration failed`
Preconfiguration lost after switchover	It was only applied to the active RP	Repeat the read-back on the standby
Interfaces up but no traffic	MTU or encapsulation mismatch between preconfiguration and what the far end expects	`show interfaces <name>` for MTU, plus far-end comparison

Building a short post-install checklist into the change window — read back the configuration, verify show configuration failed is empty, confirm interfaces are administratively up, and check the intended address is on the intended port — turns these failures into routine catches instead of overnight calls.