Introduction to Configuration Session

Configuration Session — also referred to as a candidate session or configuration candidate — is a configuration management feature on Cisco Nexus 9000 switches that allows you to stage, review, and validate a set of configuration changes before they are committed to the running configuration. Instead of editing the running configuration directly — where every keystroke takes immediate effect — Configuration Session lets you build up your intended changes in an isolated candidate buffer, diff them against the running configuration, and then apply (or discard) them as a single, atomic operation.

Configuration Session is supported on all Nexus 9000 platforms starting in NX-OS 10.6(3). The feature is accessible via the NX-OS CLI as well as the supported programmatic APIs covered earlier in this lab, which makes it equally useful for an operator typing at a console and for an automation pipeline pushing infrastructure-as-code changes.

Step 1 - Why Configuration Session?

Configuration Session brings several capabilities that directly address common operational risks when changing live network infrastructure:

• Stage, review, and validate configuration changes before committing them to the running configuration.


• Prevents accidental configuration changes — commands do not take effect on the device until the session is committed.


• Pause and resume a configuration session so a long-running change can be built up incrementally without losing work.


• Config-replace workflow support, allowing a full configuration file to be imported into the candidate session and applied as a single change.


• Rollback by commit ID, providing a fast revert path back to a previous known-good state.


• Accessible via supported programming APIs, so automation tools can drive the same staged-commit workflow used at the CLI.


• Real-time validation — commands are checked against the system as you type them, and any unsupported command is rejected immediately so you know right away if a particular feature is not yet supported within a session.

Step 2 - Operational Lifecycle

A Configuration Session moves through four logical phases from creation to commit. Understanding these phases makes it easier to reason about what state your changes are in at any given moment.

1. Initiation — The configure candidate [name <session>] command initializes a new configuration session. If no name is provided, NX-OS will auto-generate one (e.g. session-N).


2. Staging — You enter configuration commands as you normally would, but they are written into the candidate session rather than the running configuration. Each command is validated against the system in real time, and unsupported commands are rejected immediately.


3. Review & Diffing — show candidate-config displays the staged configuration, and show candidate-config diff provides a side-by-side comparison of the delta between the candidate and the running configuration. This is where you confirm the change will do exactly what you expect.


4. Commit / Abort — commit applies the candidate configuration to the running configuration as a single atomic change. abort discards the candidate session without affecting the running configuration.

Step 3 - Lifecycle Commands Reference

The table below maps each phase of the Configuration Session lifecycle to the commands you will use throughout the rest of this section of the lab. Use it as a quick reference as you work through the upcoming examples.

Operational Lifecycle	Procedure	Command(s)
Initialize	Create a configuration session. Optionally provide a session name; otherwise the system will use session-N.	configure candidate [name <session-name>]
Stage	Enter configuration commands directly, or import an existing configuration from a file into the candidate session.	Enter NX-OS CLI commands or import configuration bootflash:<filename>
Review / Diff	Review the staged configuration, diff it against the running configuration, or check the status of the candidate session.	show candidate-config [name <session-name>] show candidate-config [name <session-name>] diff show candidate summary [pending] show candidate summary [name <session-name>]
Commit / Abort	Commit the candidate updates to the running configuration, or abort to discard the candidate session. Configuration commits can also be reviewed by ID, change set, list, or session.	Within candidate session: commit | abort Outside candidate session: configure candidate name <session-name> [commit | abort] Review configuration commits: show configuration commit [id | changes | list | session]
Rollback	Roll the running configuration back to a previous commit using its commit ID.	rollback configuration commit <id>

With the lifecycle and commands in mind, continue to the next section to walk through a Configuration Session end-to-end on your pod's Nexus 9000 switch — initializing a session, staging changes, reviewing the diff, committing, and rolling back.