SONiC CLI Cheat Sheet: show, config and Docker Commands

2026年8月31日 LOG admin

SONiC (Software for Open Networking in the Cloud) has a surprisingly simple CLI model: two command families, show and config, with every subcommand abbreviable to three characters. Whether you are checking interface transceiver health, reloading the configuration database, or inspecting BGP neighbors from inside a Docker container, this cheat sheet collects the most-used SONiC commands in one place, based on the Getting Started with SONiC book by r12f.com. Each section adds the context that turns a list of commands into a working troubleshooting reflex.

Command Structure and Shortcuts

show <object> [options]
config <object> [options]

All subcommands can be abbreviated to the first three letters, so show interface transceiver error-status becomes show int tra err. Use -h or --help for unfamiliar commands.

The three-letter rule applies at every level of the command tree, and it is worth internalising because it dramatically shortens interactive work. show interfaces counters becomes show int cou; show ip bgp neighbors becomes show ip bgp nei. The rule breaks only where two siblings share their first three characters — the CLI will then tell you the abbreviation is ambiguous and list the candidates, which is faster than reading documentation. Tab completion is available in the same way it is on Linux, so the shortcut habit is easy to acquire: type three letters and press Tab.

Basic System Information

show version
show uptime
show platform summary

show version is the command you will paste into the first line of every ticket: it reports the SONiC image version, the hardware SKU, the ASIC vendor (Broadcom, Marvell, NVIDIA/Mellanox or Cisco), the serial number and the build date. The ASIC vendor matters more than it first appears, because counter names, FEC options and available show subcommands vary by silicon.

show platform summary is the fast inventory view — platform, HwSKU, ASIC and serial — and show uptime answers the question that explains a surprising share of outages: has this switch rebooted since you last looked at it? Pair uptime with show reboot-cause when the answer is unexpected.

Configuration Reload and Save

sudo config reload       # reload config from DB; restarts services (causes network interruption!)
sudo config save -y      # save current config to /etc/sonic/config_db.json

These two commands do opposite things to the running state and are worth keeping straight. config save is safe and non-disruptive: it writes the current configuration into /etc/sonic/config_db.json so that it survives a reboot. config reload is disruptive by design: it tears down services and rebuilds them from the configuration database, which briefly interrupts traffic on every interface. In production, reload is a maintenance-window operation.

SONiC keeps two copies of the file — config_db.json and its predecessor as a backup — and compares them at reload time. If you have edited the JSON by hand, note that the format is strict and a malformed file can leave the switch in a partially configured state, which is much harder to recover from than a clean rollback. Our dedicated walkthrough on saving, reloading and replacing config_db.json covers the safe sequence, including how to validate before you reload.

Docker Containers

SONiC runs each subsystem in its own container. Enter a container with docker exec:

docker ps
docker exec -it <container_id> bash

The container list is a diagnostic instrument in its own right. You will normally see the database, swss, syncd, bgp, teamd, lldp, pmon, snmp, eventd and mgmt-framework containers. A container that is missing or restarting tells you which subsystem failed, and docker logs on that container usually names the cause in its last few lines.

admin@sonic:~$ docker ps
admin@sonic:~$ docker logs --tail 200 bgp
admin@sonic:~$ docker exec -it syncd bash

To run a command in all containers, loop over docker ps output:

for id in `docker ps | tail -n +2 | awk '{print $1}'`; do docker top $id; done

The loop is the fastest way to check whether a given process is alive somewhere in the stack, or to confirm that a service is not running anywhere at all. Inside containers that need network access you will also find a docker exec shell useful for ip, ss and ping, though remember that what you see there is the container's network namespace, not the ASIC data plane.

Interfaces, MAC, ARP and Routing

show interface status
show interface counters
show interface portchannel
show interface transceiver info
show mac
show arp
show ndp
show ip bgp summary
show ip bgp neighbors [IP]
show ip route
show lldp table
show vlan brief
show acl table
show acl rule

A sensible reading order for any link problem starts with show interface status, which gives up/down state, negotiated speed, FEC mode and the port description in one table. Then show interface counters for error and drop counts, and show interface transceiver info for the optical module's identity, vendor and serial. Only if those show a physical-layer problem is it worth drilling into DOM values.

The Layer 2 and Layer 3 tables answer the other half of the question. show mac tells you whether the destination MAC is still learned on the expected port; show arp and show ndp reveal whether the IPv4 and IPv6 neighbour entries are present and how recently they refreshed; show ip route shows whether the route you expect is actually installed and points at a reachable next hop. A missing entry in any of these produces silent blackholing with perfectly clean optics.

For control-plane health, show ip bgp summary is the fastest single screen in SONiC: peer state, uptime, prefixes received, message counters and the last reset reason per neighbour. If you want the full cheat sheet of interface, transceiver and counter commands in more depth, see our main SONiC CLI cheat sheet.

MUX Cable (Dual ToR)

config muxcable mode active Ethernet4
show muxcable status Ethernet4
show muxcable firmware version <port>

In a dual-ToR design the server NIC is attached to a mux that selects one of two switches. The mode command forces the mux toward a particular ToR — active or standby — which is how you drain a ToR without touching the servers. show muxcable status reports the current mode, the peer's view, and the hardware state, so a disagreement between the two ends is immediately visible. Keep the firmware version in your records: mux firmware upgrades are one of the few maintenance actions that can silently change failover timing.

Useful adjacent commands are config interface shutdown to drain an individual port and sudo config bgp shutdown all to withdraw routes from a whole switch while you work — the latter is the cleanest way to isolate a suspect device because it never writes to CONFIG_DB.

Management VRF and Database Commands

Production switches usually keep management traffic in a separate VRF, which changes how you reach the device and how you read its tables:

show mgmt-vrf
show ip route vrf mgmt
ping -I mgmt 10.0.0.1
sudo config vrf add mgmt

The -I mgmt source-interface flag is the detail people miss when a ping from a properly routed switch fails: the packet left the wrong VRF. Our SONiC management VRF and database cheat sheet goes through the rest of the management-side commands, including the sonic-db-cli family used to read and write the Redis databases directly.

Reading the databases is often the only way to see the truth when the CLI and reality disagree:

sonic-db-cli CONFIG_DB keys 'PORT|*'
sonic-db-cli APPL_DB hgetall 'PORT_TABLE:Ethernet0'
sonic-db-cli STATE_DB keys 'PORT_TABLE|*'
sonic-db-cli COUNTERS_DB keys 'COUNTERS:*'

If a configuration change appears in CONFIG_DB but not in APPL_DB, the orchestrator never processed it — a different fault from a change that was applied but has no forwarding effect. That distinction saves hours of guessing.

Logging, Events and Evidence Collection

SONiC splits observability between a traditional syslog and an event system that records structured state changes. Both are worth knowing, because they answer different questions:

show logging
show event
show event -s "2026-09-14 08:00:00"
config syslog add 10.10.10.50
show techsupport

show logging gives the most recent syslog lines, which is where container restarts and SDK faults surface. show event reads the event database — a compact, timestamped record of significant transitions such as a port going down, a service starting, or a module being inserted. When you are asked "when exactly did this start?", the event log answers faster and more precisely than grepping syslog.

Pointing syslog at a collector with config syslog add is a one-line change that pays for itself the first time a switch reboots and takes its local logs with it. Finally, show techsupport bundles counters, routes, BGP state, transceiver readings, logs and the running configuration into an archive under /var/dump/. It is the artefact every vendor and community escalation will request, so generate it while the fault is live rather than after the device has recovered.

Port Channels and Breakout Ports

show interface portchannel
show interface portchannel member
show lacp neighbour
show interfaces breakout
config interface breakout Ethernet0 '1x400G'

Port channels are where configuration and physical reality most often diverge. show interface portchannel member lists each member and its LACP state; a member stuck in a non-collecting state is not carrying traffic, which explains a systematic throughput shortfall that no error counter ever reveals. Compare that against show lacp neighbour to confirm what the far end believes about the same bundle.

Breakout configuration changes the port layout entirely and is applied through the CLI rather than by editing JSON. Because it recreates the interfaces, it is disruptive and should be done in a maintenance window, after which show interfaces breakout confirms that the four sub-ports exist as expected.

A Practical Working Order

show version and show uptime — know the image, the platform and whether the box has restarted.
show interface status, then show interface counters — split physical errors from pipeline drops.
show interface transceiver info when errors are present, then the Layer 2 and Layer 3 tables when they are not.
show services status and docker logs if a protocol looks dead rather than broken.
sudo config save -y once the device is healthy again, so the fix survives a reboot.