Mellanox Switch CLI: Getting Started with MLNX-OS Commands

Mellanox (now NVIDIA) switches run the MLNX-OS / Onyx operating system, and getting one online is a short sequence: console wizard, management IP, SSH, then the standard enable/configure-terminal workflow. This guide walks the initial setup and the basic CLI commands every admin needs - show interfaces, configuration write, and the pipe filters that replace grep. It is written for the Ethernet and InfiniBand platforms (SX, SN and SB families) that ship with MLNX-OS 3.x, and it assumes you have physical access to the console port for the first half hour.

Everything below is deliberately conservative: no assumptions about a DHCP server, no assumptions about a pre-existing management VLAN, and no assumption that the switch has ever been powered on. That is the state most switches arrive in - on a pallet, in a box, with a factory blank configuration.

What You Need Before You Start

Gather four things first. A USB-to-serial (or RJ45-to-serial) adapter with a working driver on your laptop - the FTDI and Prolific chipsets are the usual source of a "console is dead" afternoon. A terminal program configured to 115200 baud, 8 data bits, no parity, 1 stop bit, no flow control (older SX-series boxes and some InfiniBand platforms use 9600 baud; check the hardware manual for your exact model). A note of the switch serial number and the MGT1 MAC address printed on the label, because that MAC is what you will register with the DHCP server if you go the DHCP route. And a decision: will the switch run DHCP on mgmt0 for its first boot, or will you assign a static address immediately? Both are fine; DHCP is faster to get a first session, static is what ends up in production.

MLNX-OS keeps two MAC addresses on the label: MGT1 and MGT2. In the operating system these appear as mgmt0 and mgmt1, and MGT1 maps to mgmt0. If you plug your management cable into the wrong RJ45 you will spend twenty minutes watching DHCP logs for a MAC that never shows up. Write the mapping down before you start.

Initial Console Setup

Connect the switch console port to a COM port (baud rate 115200 on the SX1710; check your hardware manual). Default username and password are both admin. The first login starts the configuration wizard:

Mellanox configuration wizard
Do you want to use the wizard for initial configuration? y
Step 1: Hostname? [switch-5fa5a0] my-switch-hostname
Step 2: Use DHCP on mgmt0 interface? [yes]
Step 3: Enable IPv6? [yes] no
Step 4: Admin password (Enter to leave unchanged)?
Configuration changes saved.

The bracketed values are defaults - pressing Enter accepts them. The hostname default is derived from the switch MAC, so the wizard's offer of switch-5fa5a0 is not a typo. Answering "no" to DHCP drops you into a static addressing flow where you supply the IP, netmask and gateway for mgmt0; answering "yes" leaves you dependent on a working DHCP scope until you change it.

The wizard only covers hostname, management addressing and the admin password. Everything else - NTP, logging, users, VLANs, ports - is configured from the CLI afterwards. If you skip the wizard and later want it back, run configuration jump-start from an enable-mode prompt, which resets the configuration and restarts the wizard.

SSH Access and CLI Modes

Once mgmt0 has an address, SSH is the working interface. The default login is admin with the password you set in the wizard, and you land in standard mode:

# ssh admin@10.20.2.54
my-switch-hostname > enable
my-switch-hostname # configure terminal
my-switch-hostname (config) #

The three levels matter. Standard mode (>) shows a restricted set of status commands. Enable mode (#) unlocks every show command plus operational actions such as reboots and firmware changes, but no configuration. Config mode ((config) #) is the only place where you can change anything, and on MLNX-OS only the admin role can enter it. The prompt string tells you immediately which level you are in, which is useful when you paste a block of commands from documentation and wonder why half of them are rejected.

Related reading: the deeper CLI reference, including mode tables, include/exclude filters and keyboard shortcuts, is in the NVIDIA MLNX-OS CLI modes and commands guide.

Basic Configuration Commands

my-switch-hostname (config) # username admin nopassword
my-switch-hostname (config) # no cli default auto-logout
my-switch-hostname (config) # configuration write
my-switch-hostname (config) # show running-config

configuration write saves the running configuration to the startup-config file - without it, all changes are lost on reboot. This is the single most common way to lose an hour of work on MLNX-OS: the configuration is applied and visible in show running-config, but a power cycle brings back the previous state.

A slightly more complete first-hour configuration, still safe to run on a lab switch, looks like this:

my-switch-hostname (config) # hostname dc1-tor-01
my-switch-hostname (config) # no cli default auto-logout
my-switch-hostname (config) # ntp server 10.20.0.10 version 4
my-switch-hostname (config) # ntp enable
my-switch-hostname (config) # clock timezone UTC
my-switch-hostname (config) # logging server 10.20.0.20
my-switch-hostname (config) # username netops password NetOps123 capability admin
my-switch-hostname (config) # configuration write

NTP before anything else: log timestamps, show logging entries and firmware-upgrade records are all far easier to correlate with NTP running. The username ... capability admin form creates a second administrator so you are not stuck if the original account is locked out.

Show Commands

The show tree is where you will spend most of your time. Start with identity and health, then move to interfaces.

my-switch-hostname (config) # show version
my-switch-hostname (config) # show inventory
my-switch-hostname (config) # show system
my-switch-hostname (config) # show interfaces mgmt0
my-switch-hostname (config) # show interfaces ethernet status
Port      Operational state   Speed      Negotiation
------    -----------------   -----      -----------
Eth1/1    Up                  40 Gbps    No-Negotiation
Eth1/2    Down                40 Gbps    No-Negotiation

my-switch-hostname (config) # show interfaces ib status

show interfaces ethernet status applies to Ethernet switches; show interfaces ib status applies to InfiniBand switches or gateway systems. On a VPI (virtual protocol interconnect) switch, the same physical port can present itself as either an Ethernet port or an InfiniBand port depending on which of the two show trees answers - that is expected, not a fault.

The counters and table commands are the second tier, and they are what you use when something looks up but behaves badly:

my-switch-hostname # show interfaces ethernet counters
my-switch-hostname # show interfaces ethernet 1/1
my-switch-hostname # show mac-address-table
my-switch-hostname # show ip route
my-switch-hostname # show lldp remote
my-switch-hostname # show system health
my-switch-hostname # show power
my-switch-hostname # show environment

show interfaces ethernet counters is the one to run before and after a suspected problem period; discarded and error counters that climb steadily point at optics, cabling or a speed mismatch, while flat counters with poor throughput point at congestion rather than a physical fault.

CLI Pipe Filters and Options

MLNX-OS does not have a shell, so grep is replaced by output modifiers appended with a pipe. They work on every show command and they are the reason you rarely need to scroll.

! filter like grep
my-switch-hostname (config) # show running-config | include ethernet

! inverse filter
my-switch-hostname (config) # show interfaces ethernet status | exclude Down

! watch mode
switch (config) # show interfaces ethernet status | watch interval 5

! count lines
switch (config) # show running-config | count

! JSON output for automation
switch (config) # show interfaces | json-print

include and exclude take a regular expression, so | include Eth1/[1-4] is valid. count is quietly one of the most useful modifiers - show running-config | count tells you how big the configuration is, and show mac-address-table | count tells you how many MAC entries are currently learned. json-print renders the output as JSON for scripting, but it cannot be combined with the filtering or watch modifiers, so use it on the raw command.

More filter and watch patterns, including log-oriented workflows, are collected in MLNX-OS CLI filters, watch and link diagnostics.

Saving, Backing Up and Resetting Configuration

Saving with configuration write keeps the config on the switch. Saving it off the switch is the step people skip until the first RMA.

my-switch-hostname # configuration write
my-switch-hostname # configuration upload running-config \
    scp://admin@10.20.0.5/backups/dc1-tor-01.cfg
my-switch-hostname # configuration fetch \
    scp://admin@10.20.0.5/backups/dc1-tor-01.cfg
my-switch-hostname # configuration jump-start

configuration jump-start returns the switch to factory settings and restarts the wizard - useful in a lab, catastrophic in production if you have not uploaded a copy first. Configuration naming and rollback conventions are covered in MLNX-OS configuration management: save, load, reset.

Verifying the First Configuration

Before you leave the switch, run a short verification pass. It takes two minutes and catches the failures that otherwise surface weeks later, when a link drops and nobody remembers whether the management path was ever redundant.

my-switch-hostname # show version | include Product|Version
my-switch-hostname # show interfaces mgmt0
my-switch-hostname # show ip route
my-switch-hostname # show ntp
my-switch-hostname # show logging
my-switch-hostname # show users
my-switch-hostname # show configuration files

Three things to confirm. First, show interfaces mgmt0 should report link up with the speed your adapter negotiated; a half-configured management interface answers ARP but drops larger packets, which looks like an SSH problem and is not. Second, show ntp should show the server as reachable and the stratum sane - an unreachable NTP server silently leaves the clock free-running, and every log entry you collect later will have a misleading timestamp. Third, show configuration files should list the startup-config you just wrote; if the file list is empty, configuration write did not take and you are one reboot away from losing the whole session's work.

show users is worth running on a shared lab switch: it tells you whether somebody else has an open session and whether anyone is in config mode. MLNX-OS allows multiple sessions, and two administrators editing the same running configuration is a reliable way to produce a state neither of them intended.

Troubleshooting Tips

• Map the MGT1 MAC address (from the switch label) to the DHCP server - MGT1 maps to mgmt0 in the OS.
• On systems with two power supplies, connect both; otherwise the power/system LEDs stay red. Unplugging the unused tray clears the red LED.
• Re-run the wizard anytime with configuration jump-start.
• If the console shows nothing at 115200, try 9600 before assuming a dead serial adapter - several SX-series platforms still default to the slower rate.
• Changes that appear in show running-config but vanish after a reboot were never written with configuration write.
• When an interface will not come up, check show interfaces ethernet 1/1 for the configured speed and force setting before swapping cables; a port forced to 40G will never negotiate with a 25G breakout.

Once the basics are in place, the natural next steps are port modes and link aggregation. See Mellanox switch port types in MLNX-OS: access, trunk and hybrid. For a console-side walkthrough of the same first hour with screenshots, see MLNX-OS first-time setup wizard.

Related articles: NVIDIA MLNX-OS LAG and LACP configuration, SONiC CLI cheat sheet, and Data center ToR switch selection.

原文链接：https://enterprise-support.nvidia.com/s/article/howto-get-started-with-mellanox-switches