NVIDIA MLNX-OS Configuration Management

2026年8月22日 LOG admin

Source: NVIDIA MLNX-OS User Manual (Switch Software Documentation)

This article covers how to manage configuration files on NVIDIA Spectrum switches running MLNX-OS (Onyx), including loading configuration, restoring factory defaults, BIN and text configuration files, and automated backups.

Configuration management on MLNX-OS is not a single "save" button. It is a small family of commands that move configuration between three distinct places: the running configuration held in RAM, the active configuration file stored in flash, and a library of named configuration files you can stage, copy off-box, or roll back to. Every operational task below — preparing a maintenance window, recovering a corrupted device, keeping an offline copy for audits — reduces to moving data deliberately between those layers. Learn which layer a command touches and the CLI stops being intimidating.

Why MLNX-OS Separates Running, Active and Named Configuration

Cisco-style CLIs blur the boundary: write memory copies running config over the saved file and most engineers never think about it again. MLNX-OS keeps the layers explicit for two reasons. First, on a data centre switch a reboot is sometimes the fastest way to activate a configuration (interface reconfiguration, routing protocol restart), so the system needs to distinguish "change it now in memory" from "make this file the one that boots". Second, Ethernet switches in large fabrics are increasingly managed as an inventory, so being able to generate, name, archive and restore whole configuration files is a first-class feature rather than an afterthought.

A useful mental model:

Running configuration — what the switch is executing right now. Change it with normal configuration commands, inspect it with show running-config. Lost on reboot unless written out.
Active configuration file — the file the switch boots from. Written by configuration write. This is the closest MLNX-OS equivalent of NVRAM in IOS.
Named configuration files — additional files in flash that you create, fetch from a server, or generate from the running configuration. They can be uploaded off-box as backups or made active with configuration switch-to.

Loading a Configuration File

By default, or after a system reset, the system loads the default "initial" configuration file. To load a different configuration file and make it the active configuration:

switch > enable
switch # configure terminal
switch (config) # configuration switch-to myconfig
switch (config) #

On director switch systems with dual management modules, load the configuration on the top CPU that serves as the chassis master. If the configuration file is loaded on a different CPU than the SM HA master (the SM HA master that serves the VIP), the SM configuration is overwritten.

Two practical notes. First, configuration switch-to only changes which file the switch will load — the running configuration is unaffected until the next reboot, so in a maintenance window the sequence is "switch-to, then reload, then verify". Second, because the file you switch to may have been captured weeks earlier, treat it as a rollback rather than an edit: after the reboot, confirm VLANs, LAGs and management reachability with show interfaces status and show running-config before you declare success.

Restoring Factory Default Configuration

If system configuration becomes corrupted, restore the factory default configuration. On a single management module system:

switch (config) # reset factory keep-basic

On a dual management module system: connect to a remote console/serial connection, remove the slave management module, run reset factory keep-basic and wait for reboot, log in as "admin" and run the Configuration Wizard, insert the slave module, remove the master module (a takeover makes the slave the new master), repeat reset factory keep-basic on the new master, insert the other module, and power cycle the system.

The keep-basic keyword matters: it clears the configuration but preserves the basics needed to reach the box again (management interface, admin credentials, licensing-level entries). Dropping it yields a truly bare device that you must console into with the default credentials printed on the chassis label — survivable in a lab, painful at 02:00 in a production rack. Always capture a text configuration file to a server before a factory reset; the reset itself does not ask for confirmation twice.

Managing Configuration Files

BIN Configuration Files

BIN configuration files are not human readable; they are encrypted and contain integrity verification preventing them from being edited. Key commands:

switch (config) # configuration new my-filename                    # create new (empty) BIN file
switch (config) # configuration upload my-filename scp://myusername@my-server/path/to/my/
switch (config) # configuration fetch scp://myusername@my-server/path/to/my/
switch (config) # show configuration files                          # list available files
switch (config) # configuration switch-to my-filename               # load (requires reboot)

A BIN configuration file uploaded from the switch is encrypted and has integrity verification — if modified in any manner, the fetch to the switch fails.

That integrity check is a feature, not an obstacle. It means a BIN file pulled off one switch can be pushed to a replacement unit of the same model and software version with confidence that nobody has hand-edited it in transit, which is exactly the property you want in a disaster-recovery workflow. Keep the files in version control or an object store keyed by serial number and MLNX-OS release; a BIN file from a different release or a different Spectrum model will refuse to load, and the error appears at fetch time rather than at boot time — much easier to debug.

Text Configuration Files

Text configuration files are text-based and editable, similar in form to the output of show running-config expanded:

switch (config) # configuration text generate active running save my-filename
switch (config) # configuration text file my-filename apply
switch (config) # configuration text file my-filename upload scp://root@my-server/root/tmp/my-filename
switch (config) # configuration text fetch scp://root@my-server/root/tmp/my-filename

Applying a text-based configuration file appends to the existing configuration; only new or changed configuration is added and no reboot is required. Applying it to an existing/running data port configuration may result in unpredictable behavior, so it is suggested to first clear the configuration or reset to factory default.

Because text files are editable, they are the right tool for templating and review: generate a file from a known-good switch, strip the identity-specific lines, keep the rest as a golden template, and apply it to new hardware. The append semantics are also the sharpest edge in the whole feature. "Append" means the file cannot remove configuration — if the target switch already has a VLAN, an interface description or an ACL that the template does not mention, that stale configuration stays. That is why the recommendation above (clear first, then apply) is not bureaucratic caution but a correctness requirement.

Choosing Between BIN and Text

Use BIN when the goal is exact restoration of one switch onto identical hardware — encrypted, integrity-checked, no editing surprises. Use text when the goal is portability and reviewability — templates across a fleet, diffs in a code review, or migration between software releases. A common production pattern is to keep both: a nightly BIN upload for disaster recovery, plus a weekly text generation that lands in Git where it can be diffed.

Automated Configuration File Backup

Auto-Upload on Configuration Write

switch (config) # configuration auto-upload remote-url "scp://root:password@my-server/path/to/upload/to"
switch (config) # show configuration auto-upload
switch (config)# configuration write

This uploads the active configuration file on every "configuration write". Use no configuration auto-upload remote-url to disable.

This is the single most valuable line of configuration on an access switch, because it removes the human step from the backup. Every change an engineer saves is mirrored to the server, so the backup you restore from is never older than the last change made. Two cautions: the URL contains a password in clear text inside the configuration file (prefer a dedicated read-only credential), and show configuration auto-upload is the only way to confirm it is armed — verify it after every firmware upgrade, because the feature is easy to leave behind during a migration.

Automated Periodic Backup with Scheduled Jobs

switch (config) # job 1
switch (config) # job 1 command 1 "configuration upload timestamp active scp://root:password@my-server/path/to/upload/to"
switch (config) # job 1 schedule periodic interval 18h0m0s
switch (config) # job 1 enable

Scheduled jobs give you a simple way to perform automated periodic backups of the active configuration.

The word timestamp in the command is doing real work: it makes each upload a new, date-stamped file rather than overwriting the previous one, which turns the destination directory into a coarse change history. A periodic job is worth configuring even when auto-upload is enabled, because it also captures drift that never reached a configuration write — not every change to a switch is deliberate, and the timestamped copies are how you date a silent change.

Backup Architecture: What to Back Up, Where, and How Often

Every switch, both formats. BIN for exact restore, text for review. Storage is cheap compared with a fabric that has no known-good configuration.
Off-box, always. A backup stored only in flash dies with the switch. SCP to a server is the minimum; a Git repository or object store with lifecycle retention is better.
Before and after every change window. The pre-change file is your rollback; the post-change file is your new baseline. Name them accordingly.
At every firmware level. A BIN file is tied to a software release. Archive one per release so a downgrade is possible without a rebuild.
Verify restores, not just uploads. A file that fetched successfully will also load successfully; a file that only ever uploaded has never been tested.

Verification Checklist

show configuration files — confirm the expected files exist and note the timestamps.
show configuration auto-upload — confirm the destination URL and that the feature is enabled.
show running-config — compare against the file you intend to make active.
configuration write — persist the running configuration to the active file, then re-check the file list.
After any configuration switch-to or reset: reload, then confirm management reachability, VLANs and LAG membership before closing the window.

Common Pitfalls

Confusing running with saved. A configuration that works today but was never written out is gone after the next power event. When in doubt, configuration write.
Applying text config onto a non-empty configuration. Parse ignores what the file does not mention; the old configuration survives underneath. Clear or reset first.
Editing a BIN file. The integrity check rejects it. BIN is a container, not a document.
Restoring a file captured on different hardware or software. Match model and release before you need the restore.
Leaving auto-upload configured with a personal account. Use a service account and rotate the credential when someone leaves.
Assuming a dual-management-module reset is half the work. Both CPUs must be reset in the documented order; a partially reset chassis behaves inconsistently.