MLNX-OS CLI Filters, watch and Link Diagnostics Commands

MLNX-OS has the most Linux-flavoured CLI of the major data centre network operating systems, and two features make it genuinely faster to troubleshoot than IOS or Junos: pipeline operators that filter, watch and reformat any show command, and per-port link diagnostics that report physical-layer state with numeric status codes. This article collects the output-processing tricks from the official MLNX-OS user manual and shows how to use them on a real switch.

CLI Modes and Completion

The MLNX-OS CLI uses Standard mode (switch>), enable mode (switch#) and configuration mode (switch (config) #). Commands support tab completion and shortened forms — en for enable, cli cl for cli clear-history — and pressing tab twice after a letter lists all possible completions. Error responses begin with a percent sign, so % at the start of a line means the command was rejected.

Filtering Show Output with include and exclude

Any show command can be piped to a filter with | include or | exclude plus an extended regular expression, with optional case-insensitivity and context lines:

switch (config) # show interfaces ethernet | include "up" ignore-case
switch (config) # show interfaces ethernet 1/1 | exclude "0 packets"
switch (config) # show mac address-table | include "00:02:c9" next 2 prev 2

Multiple filters can be chained, and quoted strings allow spaces inside the pattern. This replaces the IOS habit of piping through grep and gives you context lines in one step.

Monitoring with watch, count and json-print

Watch a counter or state change live without repeated manual pings — ideal during a failover test or a firmware upgrade:

switch (config) # show interfaces counters | watch interval 5
switch (config) # show interfaces counters | watch diff interval 2
switch (config) # show mac address-table dynamic | count
switch (config) # show interfaces ethernet 1/1 | json-print

| watch refreshes the output at the interval you set (2 seconds default) until Ctrl+C; adding diff highlights what changed between refreshes. | count prints only the number of output lines. | json-print returns the state in structured JSON for scripting — note it cannot be combined with include/exclude or watch. See our MLNX-OS getting started guide for the base command set.

Why Pipeline Operators Beat "grep on the NMS"

Most network teams troubleshoot a suspected bad port by SSHing in, running a show command, scrolling, and repeating. The pipeline operators turn that loop into a single command that keeps running - and critically, they run on the switch, over the same management session, rather than requiring you to export data to a collector that may itself be affected by the problem you are diagnosing. When a LAG is flapping or a firmware upgrade is in progress, the switch is the only vantage point guaranteed to be current, and | watch diff is the cheapest possible "diff of interface state over time".

The operators are also composable: because they accept extended regular expressions, you can encode real intent rather than literal strings. Filtering show interfaces ethernet | include "^Eth1/([1-9]|1[0-9]|2[0-4])" ignore-case isolates a port range; include "down|err-disabled" ignore-case catches anything unhealthy in one pass.

Filtering in Practice: Five Patterns Worth Memorising

# 1. which ports are physically up right now
switch (config) # show interfaces ethernet | include "up" ignore-case | count

# 2. ports with errors or discards on the receive side
switch (config) # show interfaces ethernet | include "error|discard" ignore-case

# 3. find the uplink a MAC is learned on, with context
switch (config) # show mac address-table | include "00:02:c9:12:34:56" next 1

# 4. LLDP neighbours on a single port
switch (config) # show lldp interfaces ethernet 1/49 | include "SysName|Chassis"

# 5. any interface description containing the word "prod"
switch (config) # show interfaces ethernet | include "prod"

Chaining filters is where the model pays off: apply | include to narrow a large table, then pipe the result into | exclude to drop the benign rows (the classic being exclude "0 packets"). Each filter processes the output of the previous one, so the order matters - filter cheaply and broadly first.

Link Diagnostics: Decoding the Status Codes

When a port will not come up, the link-diagnostics commands show exactly what the physical layer sees:

switch (config) # show interfaces ethernet link-diagnostics
Interface            Code  Status
---------------------------------------------------------------
Eth1/1               0     No issue was observed
Eth1/2               1024  Cable unplugged
Eth1/3               2     Auto-Negotiation failure
Eth1/4               1     The port is closed by command

The numeric codes map to physical-layer conditions: 0 means the port is healthy, 1024 reports an unplugged cable, 2 flags an auto-negotiation failure and 1 means the port was administratively closed. This single command separates a dead SFP or cable from a configuration problem in seconds. For the LAG and LACP side of MLNX-OS operations, our MLNX-OS LAG configuration guide picks up where the physical layer leaves off.

Reading the Diagnostic Codes as a Triage Ladder

Treat the code as the first rung of a ladder, and walk it in order - the point is to stop guessing about layers that the code has already ruled out:

1. Code 1 (port closed by command). The switch did what it was told. Check show interfaces ethernet 1/4 for Administrative status and look for a stored shutdown; confirm nothing in a startup script or ZTP flow is disabling the port.
2. Code 1024 (cable unplugged). The optical or copper path is open. Reseat the module, swap the patch lead into a known-good pair, check the far-end port's own diagnostics - and if the far end reports "up" with a different speed, you have a negotiation edge case rather than a dead cable.
3. Code 2 (auto-negotiation failure). Both ends are advertising incompatible capabilities, or one is fixed and the other is auto. Pin the speed and duplex explicitly on both ends and re-test; on 10/25/40/100 G links this is usually a break-out cabling or DAC/AOC compatibility issue.
4. Code 0 on both ends but no traffic. The physical layer is fine, so move up: show interfaces ethernet 1/1 status for link state, show mac address-table for learning, and the LACP view if the port is in a bond.
5. Escalate only after measuring counters. A port can be "up" and still dropping every frame; show interfaces ethernet 1/1 | include "error|discard" and a watch diff on the counters turn a vague "the link is flaky" into an incrementing number you can point at.

Keeping the pair of commands together - diagnostics for the state, counters for the behaviour - covers the overwhelming majority of "port down" tickets on a Mellanox fabric.

Counting and Automation-Friendly Output

| count is deceptively useful because it works on any show output: count dynamic MAC entries before and after a change, count ports in an up state to spot a partial fabric outage, count ARP entries on a routed VLAN. Because it returns a single number, it drops straight into a monitoring check.

| json-print is the scripting hook. It emits the parsed state of the command as JSON, which means you can pipe it through jq on a management host and act on individual fields without screen-scraping column widths:

ssh admin@switch "show interfaces ethernet 1/1 | json-print" | jq '.'
ssh admin@switch "show mac address-table dynamic | json-print" | jq 'length'

The limitation to remember is that json-print is exclusive: it cannot be combined with include, exclude or watch. When you need both filtering and structure, run the JSON form and filter on the client side - the regex operators are for human eyes on an interactive session, JSON is for tools.

What the Filters Actually Accept

The include and exclude operators take an extended regular expression, not a substring, which changes how you write patterns in three ways worth internalising:

• Anchors are literal by default for the whole line. ^ and $ match the start and end of the output line, so include "^Eth1/1 " pins the filter to lines that begin with that interface name - useful when similar names appear in both the interface column and a comment.
• Alternation and grouping work. include "down|err-disabled" matches either token; (^| )UP( |$) avoids matching UPLINK when you only want the state word.
• Quantifiers and classes are supported. [0-9], +, * and ? behave as in grep -E, so port-range and counter patterns are compact.
• Case is case-sensitive unless you say otherwise. ignore-case applies to the filter it is attached to; with several chained filters, decide per filter whether you want it.
• Quoting protects spaces and metacharacters. Anything containing a space or a character your shell would interpret should sit inside double quotes.
• Context is a first-class option. next N and prev N add N lines of trailing or leading context, which the pipe-based approach on other platforms cannot do without a second tool.

A Worked Example: Chasing a Flapping Uplink

Suppose a host intermittently loses connectivity and you suspect the switchport. The sequence below uses only the operators described here and resolves the question inside one SSH session:

# 1. Is the port physically healthy?
switch (config) # show interfaces ethernet 1/49 link-diagnostics

# 2. What does the state say, and which MACs are learned here?
switch (config) # show interfaces ethernet 1/49 | include "status|speed|duplex" ignore-case
switch (config) # show mac address-table | include "Eth1/49" | count

# 3. Watch the counters live for a minute and look for increments
switch (config) # show interfaces ethernet 1/49 counters | watch diff interval 3

# 4. Is it a member of a bond, and is the bond healthy?
switch (config) # show lacp | include "Eth1/49" next 2

If step 1 returns code 0 and step 3 shows receive errors climbing in step with the disconnects, the fault is in the physical path or the far-end NIC rather than the configuration. If step 3 is flat and step 4 shows the port repeatedly joining and leaving a LAG, the problem is negotiation or LACP timing. Reaching that conclusion in four commands, with the evidence visible as the counters move, is precisely what the pipeline design is for - and it is why these operators are worth practising on a quiet switch before you need them during an incident.

Session Management While You Troubleshoot

switch (config) # cli clear-history          # cli cl in short form
switch (config) # show cli
switch (config) # terminal length 0          # disable paging for a scroll-free session
switch (config) # no cli default prefix       # stop the mode prefix appearing

Setting terminal length 0 at the start of a troubleshooting session is the difference between a command that prints a full table and one that stops at a page break, and it is a prerequisite for any form of automated capture. show cli confirms your current session settings, and cli clear-history removes the command history when you are working on shared admin credentials.

Finally, note that | watch holds the session open by design - that is the point - so run it in a dedicated SSH window rather than in a script, and remember that a stale watching session consumes a management VTY line on platforms with limited concurrent sessions. If you are also driving the switch from configuration management, see MLNX-OS configuration management for how to snapshot and roll back the config before and after a change, and the companion post on watch and log troubleshooting for applying the same operators to the event log. For VLAN and routing context on the same CLI, our MLNX-OS VLAN and IP routing guide covers the L2/L3 side, and for lossless RoCE fabrics the counters and diagnostics here pair with the tuning in our RoCEv2 PFC/ECN deep dive.

原文链接：https://networking-docs.nvidia.com/mlnxosum/3126200lts/command-line-interface-cli