The NVUE object model, revisions and snippets
S2·E1The line nobody deleted · Dell lab bench, 01:12, dialled into the customer's change window, eleven days from acceptance
Before you read: what do you already know?
3 quick questions. Wrong answers are fine and expected; trying first makes the lesson stick.
After this lesson you can
- Describe NVUE as a schema-driven object model with four command families and three configuration revisions.
- Apply the change-control verbs (diff, apply --confirm, detach, replace, patch) that keep a remote leaf reachable.
- Predict what happens to a hand-edited /etc/frr/frr.conf or /etc/network/interfaces on the next apply.
- Write an NVUE snippet for a feature NVUE does not model, and state the rules that constrain it.
Episode 1 — The line nobody deleted
You are two hours into the change window, on a bridge with the customer’s network lead, working a pilot leaf in a cage two states away. The Dell SE is on mute with cold coffee and the spreadsheet where every promise this account has made gets a row; this one is a thirty-two leaf, two-tenant fabric for a GPU-rental business, and an acceptance review that releases the rest of the order. Three weeks ago somebody added a BGP line to /etc/frr/frr.conf by hand, and it worked. Tonight an unrelated nv config apply runs and the line is gone. Nobody typed a delete, and the lead is asking what ate his configuration.
Nothing ate it. NVUE is a schema-driven object model of the whole switch, and it renders /etc/network/interfaces and /etc/frr/frr.conf from that model every time it applies.[3] The hand edit survived exactly until the next unrelated change, weeks later and by someone else, which is why this always arrives described as a random regression.
This is what the model exists to solve. When a switch’s state is the sum of whatever files people have touched, no two boxes are alike and no automation can be trusted. NVUE makes one schema the owner, exposes it identically through the CLI and a REST API, and splits every change into three revisions — pending, applied, and a startup revision in /etc/nvue.d/startup.yaml.[1][3]
If you want a line to survive, it has to live in the model.
The lead writes it on the first page of a new notebook. You start where his night ends.
1One model, two front ends
NVUE is “an object-oriented, schema driven model of a complete Cumulus Linux system (hardware and software)”.[3] The model itself is defined with the OpenAPI Specification v3.0.2, and the consequence is the sentence that matters for automation: “The CLI and the REST API are equivalent in functionality.”[1] Anything you can type you can also PATCH, and anything you can PATCH has a nv form you can show a customer on a console.
The CLI has exactly four command families: configuration (nv set, nv unset), monitoring (nv show), management (nv config), and actions (nv action).[3] Actions are the imperative verbs that do not belong in a configuration file - nv action ping, nv action traceroute, nv action clear, nv action fetch, nv action install, and nv action reboot, which requires no-confirm.[3]
The REST side is served by nvued, installed and enabled by default, listening on port 8765; disable it with nv set system api state disabled or move it with nv set system api port <port-number>.[6] Authentication is HTTP basic with switch credentials, and there is one upgrade trap worth memorising: after upgrading to 5.6 or later you must “change the password for the cumulus user; otherwise you see 403 responses”.[6] A shape to recognise in a customer’s Ansible run:
curl -u 'cumulus:cumulus' --insecure https://127.0.0.1:8765/nvue_v1/interface
curl -u 'cumulus:cumulus' --insecure https://127.0.0.1:8765/nvue_v1/?rev=applied
curl -u 'cumulus:cumulus' -H 'Content-Type: application/json' -X PATCH \
https://127.0.0.1:8765/nvue_v1/interface/lo/ip/address?rev=2 -d '{"99.99.99.99/32": {}}'The path shape is /nvue_v1/<resource>/<path>, and the supported top-level objects are acl, bridge, evpn, interface, mlag, nve, platform, qos, router, service, system and vrf; the complete endpoint list lives in NVIDIA’s API browser tool.[6]
2Three revisions, and where configuration actually goes
Every change lives in one of three revisions: pending after nv set or nv unset, applied after nv config apply, and startup, the persisted revision.[3] Startup is a file: /etc/nvue.d/startup.yaml, written when configuration is saved and replayed at boot by nvue-startup.service.[3][2]
Since Cumulus Linux 5.9, nv config apply saves to startup automatically; nv config save is only needed when auto-save has been disabled.[4] That single behaviour change explains a whole class of tickets: on 5.9 and later “the config disappeared after reboot” is usually something else, and on older code it was almost always a missing save.[4] The habit that catches both is nv config diff startup applied before any reboot.[13]
You read a specific revision the same way you read anything else. nv show --pending, nv show --applied, nv show --startup and nv show --operational select the view; nv show --output json|yaml|auto|native selects the format; and filters such as nv show interface --filter mtu=1500 narrow the result.[3] The --operational view is the one to reach for when a customer insists the configuration is right - it shows what the system is doing, not what it was told.
- nothing run yet — start with `nv set`.
Pending revision
- Where `nv set` and `nv unset` land. Nothing is running yet — the switch behaves exactly as it did before.
- Read it with `nv show --pending`. Before every apply, read `nv config diff startup pending`.
- `nv config detach` throws away every pending change made since the last apply.
Blocked destinations: /bin, /sbin, /boot, /root, /sys, /proc, /dev. One snippet per file, set/unset only, 1 MB cap on flexible snippets.
nv action generate system tech-support # or: sudo cl-support nv config apply nv config save # writes /etc/nvue.d/startup.yaml nv config show -o commands > backup.config scp cumulus@leaf01:/etc/nvue.d/startup.yaml . nv config diff startup applied # must be empty before the reboot
Destructive ONIE install keeps the config only with -t /etc/nvue.d/startup.yaml. 5.18.0 adds automatic snapshots in /var/lib/config-backup/ (512 MB cap) restored with nv action restore system config backup <path>.
Upgrading Cumulus Linux · DGX SuperPOD switch update guide · 5.18 What's New · NVUE object model
3The verbs that keep a remote leaf alive
The nv config surface is small enough to memorise, and the release each verb arrived in matters when a customer runs an older LTS.[4]
| Verb | What it does | Introduced |
|---|---|---|
nv config apply [<revision>] |
Applies pending, or a named revision (applied, startup, empty, a revision number) |
5.0.0 |
nv config save |
Writes applied to /etc/nvue.d/startup.yaml |
5.0.0 |
nv config diff <base> <target> |
Compares two configurations | 5.0.0 |
nv config detach |
Discards all pending changes since the last apply | 5.0.0 |
nv config patch <file> |
Merges a YAML or command-text file into pending | 5.0.0 |
nv config replace <file> |
Replaces the whole pending config - include everything you want kept | 5.0.0 |
nv config revision / history |
Lists revisions and apply history with user and timestamp | 5.5.0 / 5.0.0 |
nv config translate revision <id>|filename <file> |
Converts a revision or YAML file into nv commands |
5.12.0 |
nv config verify [filename <file>|revision <rev>] |
Validates without applying | 5.17.0 |
nv config lookup <search-path> |
Retrieves configuration by space- or slash-separated path | 5.18.0 |
The safety net is nv config apply --confirm [time]: it “Applies with rollback protection”, and if nobody confirms inside the window the switch rolls back on its own; --confirm-status reports where you stand.[3][4] The default window is ten minutes, and <time> takes an explicit unit - seconds (s), minutes (m) or hours (h) - so nv config apply --confirm 60m requires you to confirm within one hour.[4]
Two backups, not one. nv config save plus scp of startup.yaml gives you the YAML; nv config show -o commands > backup.config gives you the command form, which survives a schema change that a raw YAML restore may not.[13] From 5.18.0 the switch also keeps automatic snapshots itself: applied snapshots in /var/lib/config-backup/auto-snapshots/applied/, weekly snapshots in .../weekly/, capped at 512 MB with the oldest deleted first, restored with nv action restore system config backup <snapshot-path> [force] - which creates a pre-restore rollback snapshot, rebuilds NVUE state and reboots.[2][4]
4NVUE owns the Linux files - snippets are the sanctioned exception
The hard rule: “NVUE commands replace the configuration in files such as /etc/network/interfaces and /etc/frr/frr.conf.”[3] NVUE renders those files from its model on every apply. A hand-edited BGP line survives exactly until the next unrelated nv config apply, which may be weeks later and by someone else - which is why this failure always looks like a random regression rather than a config error.
For features NVUE does not model, use a snippet. Traditional snippets target /etc/network/interfaces, /etc/frr/frr.conf, /etc/frr/daemons, /etc/cumulus/switchd.conf, /etc/cumulus/datapath/traffic.conf and /etc/ssh/sshd_config.[5] The rules are narrow: “You can only set or unset a snippet; you cannot modify, partially update, or change a snippet”; one snippet per configuration file; flexible snippets cap at 1 MB.[5] NVUE “does not validate the snippet text but does ensure that the destination conforms to NVUE policy during apply”, and writes to /bin, /sbin, /usr/bin, /usr/sbin, /lib, /lib64, /boot, /root, /sys, /proc, /dev, /var/lib/dpkg and /var/lib/rpm are blocked.[5]
The YAML shape, applied with nv config patch <file>.yaml then nv config apply:
- set:
system:
config:
snippet:
frr.conf: |
<raw FRR config>One upgrade rule closes the loop: “Before upgrading Cumulus Linux, remove snippets for features now supported natively by NVUE.”[5] Leave both in place and the file content becomes a race between the snippet and the model.
5Rehearsing the discipline without a switch
Two constraints shape every lab in this course. Cumulus VX is no longer released as a standalone image: “NVIDIA no longer releases Cumulus VX as a standalone image. To simulate a Cumulus Linux switch, use NVIDIA DSX Air.”[8] Air is reached at dsx-air.nvidia.com.[11] And a virtual Cumulus switch runs a real control plane but not the ASIC: the documented list of features that do not work virtually includes ACLs, ISSU, PTP, SPAN/ERSPAN, QoS (shaping, buffer management, packet marking), WJH, NAT, adaptive routing, storm control, OpenTelemetry and ASIC monitoring, while “full data plane functionality through the Linux kernel”, layer-2 VLANs, and VXLAN bridging and routing do work.[10]
Everything in this lesson is control plane, so all of it is exercisable in DSX Air with the same nv binary a real leaf runs.[10][11] That is not true of the RoCE and adaptive-routing modules later in the course, and saying so plainly to a customer is part of the job.
For the Dell lab there is no Spectrum switch, but the nv surface is not exclusive to switches: NVIDIA’s HBN service is configured with NVUE inside its container and the HBN documentation points at the same NVUE CLI reference rather than defining its own.[12] The HBN 3.5.0 configuration page does not publish a list of which nv command families are supported inside the container, so treat any HBN-side nv verb as unverified until you have run it and read the error.[12]
Situation. leaf01 is in a remote cage. You must change the management address family configuration and you have exactly one SSH session, over the very path you are about to touch.
Step 1 - back up in both forms. Reasoning: the YAML is the fast restore; the command form is the one that survives a schema change.[13]
nv config save
nv config show -o commands > /tmp/leaf01-backup.config
scp /tmp/leaf01-backup.config you@jump:/backups/Step 2 - stage, do not apply. nv set writes pending only.[3]
nv set interface swp1 ip address 10.0.0.1/30
nv set interface swp1 description spine01_swp1Step 3 - read the diff against startup. This answers “what will this box look like after a reboot”, which is the question that matters at 03:00.[4]
nv config diff startup pendingStep 4 - validate before applying. nv config verify arrived in 5.17.0; on an older LTS skip this step and rely on the confirm timer.[4]
nv config verifyStep 5 - apply with rollback protection, then prove you are still alive.[3]
nv config apply --confirm <time>
# from a SECOND session, or after re-testing the path you just changed:
nv config apply --confirm-status
nv config apply --confirm # confirm only once the path is provenStep 6 - if the change was wrong and you still have a prompt. nv config detach throws away pending; if you already applied, re-apply the startup revision.[4]
nv config detach # pending only
nv config apply startup # roll applied back to what bootsAcceptance. nv config diff startup applied returns nothing, and nv show interface swp1 --operational shows the address you intended.
Fill the blanks for the same change on a leaf running Cumulus Linux 5.11 (an LTS line, so no nv config verify).
nv config ____ # persist current state to startup.yaml
nv config show -o ____ > /tmp/leaf01.config # backup form that survives a schema change
nv set interface swp1 ip address 10.0.0.1/30
nv config ____ startup pending # what will this look like after a reboot?
nv config apply --____ <time> # rollback protection
nv config apply --____ # check whether the window is still open
nv config ____ # if you change your mind before applyingState in one line why nv config verify is missing on this release, and which verb you rely on instead.
A customer’s automation applies configuration through the REST API. Overnight, one leaf reboots and comes back without the VLANs the automation created; the other 31 leaves are fine. The automation logs show HTTP 200 for every call on every switch.
Produce, with acceptance criteria: (1) the two revisions you would diff first and what result would confirm your hypothesis; (2) the single release-dependent behaviour that would explain the difference between this leaf and the others; (3) the nv command that proves whether the API path and the CLI path disagree; (4) a one-paragraph change to the customer’s runbook that prevents a recurrence without adding a second tool.
Acceptance: your answer names a revision pair, a release boundary, one command, and a runbook line that a network engineer could paste into a change ticket unchanged.
What you send at 02:00
The line goes back as a snippet, so the model owns it and the next apply re-renders it instead of erasing it.[5] You re-apply with nv config apply --confirm 10m, prove from a second session that the path still works, and only then confirm — on a leaf nobody can walk up to, a mistake should undo itself.[3] Then two backups leave the box: startup.yaml and the command form.[13]
What you say to the lead: “Nothing deleted it. NVUE rewrites those files from its own model on every apply, so anything you want kept has to live in the model.”
The SE, unmuted, adds a row: the thirty-two staging leaves will image and configure themselves, untouched, before the hosts land. At 08:40 the integrator calls. Twenty-nine of them did.
Lab
Goal. There is no Spectrum switch in the Dell lab, so rehearse the change-control discipline on the BlueField-3 you do have. Nothing here changes a setting; every step is a read or a file write on the host.
Pre-flight inventory, before anything:
mst start && mst status -v
mlxconfig -d /dev/mst/<dev> q > before.txt
flint -d /dev/mst/<dev> q >> before.txt
ip -br link ; ip -br addr >> before.txt- Read
before.txtand write, for each setting you might plausibly change this week, the exact command that puts it back. A rollback line you have not written down does not exist. Expected: a two-column table, planned mutation and its inverse. - Diff discipline without NVUE: re-run the same query into
after.txtanddiff before.txt after.txt. Expected: empty output, because you changed nothing yet. This is thenv config diffhabit expressed in MFT. - Store both files off the host, the way you would
scpstartup.yamloff a leaf.[13] - Optional, if an HBN container is running on the BF-3: open a shell inside it and try
nv show system,nv config diff, andnv config show -o commands. The HBN 3.5.0 documentation configures the service with NVUE and points at the NVUE CLI reference, but it does not publish whichnvfamilies are supported inside the container, so record which of the three verbs actually answer.[12] Expected: a short list of verbs that work; treat anything you did not test as unavailable. If a verb errors, capture the message verbatim - that list is a genuinely useful artefact for a customer call.
Rollback for this lab. None is needed: no step mutates firmware, mode or configuration. If you extend the lab to a real mutation, the rule from step 1 applies - write the inverse command before you run the forward one.
Goal. Feel the revision model, including a rollback you did not ask for. All of this is control plane, so DSX Air is a faithful environment for it.[10]
- In DSX Air (
dsx-air.nvidia.com) create a simulation from Blank Canvas and drag in one Cumulus node.[11] Expected: the node boots and you can open a console. If not: check the node’s OS image selection - Cumulus VX builds are available inside Air even though the standalone image is gone.[14] nv show system versionandnv show system image. Expected: a 5.x version string. If not: you are on a non-Cumulus node.- Take the two backups:
nv config savethennv config show -o commands > backup.config. Expected: a file ofnv set …lines. If not: check that you rannv config applyat least once.[13] - Stage a change:
nv set interface lo ip address 10.10.10.101/32. Expected: no output, nothing running yet. Confirm withnv show interface lo ip address --applied(old value) versus--pending(new value).[3] nv config diff startup pending. Expected: the single added address. If not: you applied by reflex -nv config detachand start again.nv config apply --confirm 2m, then do nothing. Expected: the change goes live and is rolled back automatically about two minutes later;nv config apply --confirm-statusreports the state while the window is open.[3][4] If nothing rolls back: check you passed the unit (2m, not a bare2) and that no second session confirmed the apply - the default window is ten minutes, so a bare number that is accepted will keep you waiting far longer than you expect.- Repeat step 4-5, apply normally, then
nv config show -o commandsand compare againstbackup.config. Expected: exactly one added line. - Snippet drill. Write
snippet.yamlwith thesystem: config: snippet: frr.conf:shape from segment 4, apply it withnv config patch snippet.yamlthennv config apply, and prove the raw text landed withcat /etc/frr/frr.conf.[5] Expected: your literal text appears in the file. If not: check indentation - the destination key must be the file name, and only one snippet per file is allowed. - Now remove it. The documented removal is set-or-unset, not a partial edit: edit
snippet.yaml, change the top-level- set:to- unset:keeping the same destination key, thennv config patch snippet.yamlandnv config apply.[5] Expected: your literal text disappears from/etc/frr/frr.confon the next render. If not: the destination key undersnippet:must still match the file name exactly - an unset against a different key removes nothing and reports no error.
Retrieval check
10 questions from memory. Answer before looking anything up; misses become flashcards.
Explain it to a Dell SE
Explain to a Dell SE who lives in OS10, in four sentences, what replaces `copy running-config startup-config` on a Cumulus switch and why their habit of editing /etc/frr/frr.conf by hand will lose them a maintenance window.
Sources
Facts in this lesson were checked against Cumulus Linux 5.18 documentation and the NVUE command reference, fetched 2026-09-07. Dates are when each page was fetched.
- NVUE Object Model | Cumulus Linux 5.18 · fetched 2026-09-07
- NVUE CLI | Cumulus Linux 5.18 · fetched 2026-09-07
- NVUE CLI | Cumulus Linux 5.13 · fetched 2026-09-07
- NVUE Reference - Config Commands · fetched 2026-09-07
- NVUE Snippets | Cumulus Linux 5.18 · fetched 2026-09-07
- NVUE API | Cumulus Linux 5.18 · fetched 2026-09-07
- New and Removed NVUE Commands | Cumulus Linux 5.18 · fetched 2026-09-07
- What's New | Cumulus Linux 5.18 · fetched 2026-09-07
- Upgrading Cumulus Linux | Cumulus Linux 5.18 · fetched 2026-09-07
- Cumulus Linux in a Virtual Environment | Cumulus Linux 5.18 · fetched 2026-09-07
- NVIDIA DSX Air User Guide · fetched 2026-09-07
- DOCA HBN Service Configuration (HBN 3.5.0) · fetched 2026-09-07
- NVIDIA Spectrum Ethernet Switches | DGX SuperPOD / BasePOD Update Guide · fetched 2026-09-07
- Custom Topology | NVIDIA DSX Air · fetched 2026-09-07
The same idea elsewhere
Other lessons that cover this ground, sometimes from another course's angle.
- Automating NVUE: REST API, config templates and AnsibleElsewhere in this course · Same ground: snippets, NVUE snippet and api
- Upgrades that do not lose the fabricElsewhere in this course · Same ground: backup, NVUE and versions
- HBN: BGP/EVPN on the serverDOCA course · Same ground: troubleshooting, NVUE and frr