SONiC CLI Cheat Sheet: Management VRF and Database Commands

2026年9月2日 LOG admin

SONiC (Software for Open Networking in the Cloud) hides most of its state in a Redis-backed set of databases - CONFIG_DB, STATE_DB, APPL_DB and friends - and the supported way to change things is the config CLI rather than editing the database by hand. This cheat sheet, distilled from Wikimedia's production SONiC operations wiki, covers the commands that matter when you run SONiC switches for real: management VRF access, configuration persistence, database inspection and container debugging.

What makes SONiC unusual among network operating systems is that there is no opaque running-config file. Every feature is a small daemon, every daemon reads and writes well-known keys in Redis, and the CLI is a thin, friendly wrapper that writes those keys for you. Once you understand that layering, the whole system becomes inspectable: if a feature is misbehaving, you can look at the exact key that controls it, see which container owns it, and read that container's logs. That is a very different debugging experience from a monolithic NOS.

The Databases You Will Meet

Redis runs once inside the redis container and serves up a dozen logical databases, each with a distinct role:

CONFIG_DB — the intended configuration. This is what config writes and what the switch replays at boot from /etc/sonic/config_db.json.
APPL_DB — the compiled, validated view of the configuration after the orchagent has processed CONFIG_DB entries into internal objects.
STATE_DB — the observed operational state: interface up/down, link speed, neighbour tables, container health.
ASIC_DB — the low-level programming sent to the switch ASIC by syncd. Useful for deep troubleshooting and almost never edited.
COUNTERS_DB — hardware counters for interfaces, queues, buffers and ACLs.
Others — FLEX_COUNTER_DB, LOGLEVEL_DB, SNMP_OVERLAY_DB, RESTAPI_DB, EVENT_DB and, on newer builds, GPV2_ASIC_DB for the gNMI path.

The rule that keeps you out of trouble is simple: read anything, write only through config. Writes straight into CONFIG_DB appear to work but are lost on the next reload unless you also save, and they bypass the validation the orchagent performs.

Running Commands from the Management VRF

On many SONiC builds management traffic must go through the mgmt VRF, so plain ping fails. Prepend the command:

sudo ip vrf exec mgmt ping apt.wikimedia.org
sudo ip vrf exec mgmt curl -I https://example.com

The reason is that SONiC keeps the management interface in a dedicated VRF so it cannot be confused with the front-panel data plane, and the default routing table does not contain the management default gateway. Anything that needs to reach the outside world — package repositories, DNS, an NTP source, an upgrade server — must be wrapped. Useful variants:

sudo ip vrf exec mgmt ping -c3 8.8.8.8
sudo ip vrf exec mgmt traceroute 10.0.0.1
sudo ip vrf exec mgmt nc -vz collector.local 514
ip route show vrf mgmt

The last command confirms the management default route actually exists. If it is missing, the switch cannot reach anything off-subnet and no amount of ip vrf exec will help.

Configuration: The config Tool and config_db.json

All configuration is stored in a Redis database, and SONiC provides wrapper tools. The recommended path is sudo config, which supports tab completion and --help:

sudo config save -y

This writes the running config to /etc/sonic/config_db.json, the file that is reloaded on boot. After any config change, save it or the change is lost on reboot.

The config trees you will use most often:

# Interfaces
sudo config interface ip add Ethernet0 10.0.0.1/31
sudo config interface startup Ethernet0
sudo config interface shutdown Ethernet0
sudo config interface mtu Ethernet0 9100
# VLANs and members
sudo config vlan add 100
sudo config vlan member add -u 100 Ethernet0
# LAG / port channel
sudo config portchannel add PortChannel01
sudo config portchannel member add PortChannel01 Ethernet8
# Management and hostname
sudo config hostname leaf-01
sudo config save -y

Three companion commands complete the picture. config reload -y re-applies config_db.json to a running system — it is a soft restart of the data plane, not a reboot, and it will briefly disrupt traffic. config load <file> -y merges or replaces the loaded configuration from an arbitrary JSON file without touching the saved one, useful for staging a change. And config replace <file> swaps the entire configuration atomically, which is what a configuration-management system should use.

Confirm what the switch will actually boot with by reading the saved file back rather than trusting the running state:

sudo cat /etc/sonic/config_db.json | python3 -m json.tool | head -40

Database Operations with sonic-db-cli

Sometimes you must talk to the database directly. Dump a key, or the whole running configuration, as JSON:

sonic-db-dump -y -n CONFIG_DB -k 'SECURITY_PROFILES|default'
sonic-db-dump -y -n CONFIG_DB

Key/value access and writes use sonic-db-cli with the standard Redis verbs:

sonic-db-cli CONFIG_DB hgetall 'SECURITY_PROFILES|default'
sonic-db-cli CONFIG_DB hmset 'SECURITY_PROFILES|default' certificate-name default
sonic-db-cli CONFIG_DB hdel 'SECURITY_PROFILES|default' NULL

Globbing with * is supported in -k for dumps. Messing directly with the DB is discouraged - always prefer config when an abstraction exists.

The read-only commands are safe and genuinely useful, so learn these first:

sonic-db-cli CONFIG_DB KEYS '*'                      # every configured key
sonic-db-cli CONFIG_DB KEYS 'VLAN|*'                 # one table
sonic-db-cli STATE_DB hgetall 'PORT_TABLE|Ethernet0' # observed state
sonic-db-cli COUNTERS_DB hgetall 'COUNTERS:oid:0x...'# asic counters
sonic-db-cli APPL_DB KEYS '*'                        # compiled objects
sonic-db-cli STATE_DB KEYS 'PROCESS*'                # container status

Two habits make direct database work safe. First, always read STATE_DB alongside CONFIG_DB when something is broken: a configuration key that exists but has no corresponding state entry tells you the orchagent never acted on it. Second, when you do write, note the exact value you are replacing so you can put it back — there is no undo.

Show Commands and State Inspection

The most common operational questions are answered by a handful of commands, and they are worth memorising because they are faster than querying the databases:

show version                      # image, build, kernel
show platform summary             # ASIC, platform, HWSKU, serial
show interfaces status            # link state, speed, MTU, lanes
show interfaces counters -a       # all port counters
show ip interface                 # L3 addresses and admin/oper state
show ip route                     # routing table (all VRFs)
show vlan brief                   # VLANs and members
show portchannel summary          # LAG members and status
show lldp table                   # neighbours
show techsupport                  # generate a full diagnostic bundle
show logging -f                   # tail the syslog

show techsupport produces a tarball under /var/dump/ containing logs, database dumps and counters — the single most useful artifact to attach to a vendor ticket, and one worth generating before a disruptive change.

Docker Containers: Every Feature Is a Container

Functional areas (BGP, LLDP, gNMI, syncd) run as Docker containers, so standard Docker commands work:

docker ps
docker exec gnmi cat /etc/supervisor/conf.d/supervisord.conf
docker inspect gnmi

To understand what a container does, inspect it: docker inspect gnmi shows the mounted host directories and the supervisor entry point, then docker exec into the container to read its config scripts and see exactly which DB keys control the daemon.

The container names map directly onto features, which is what makes this so useful:

swss — the switch state service: orchagent, portsyncd, and the collectors that turn APPL_DB into ASIC programming.
syncd — the ASIC driver, talking the SAI API to brass.
bgp — FRR, the routing stack (bgpd, zebra, staticd).
teamd — LAG/LACP control plane.
lldpd, snmp, telemetry, gnmi, pmon, sflow, dhcp_relay, radv, macsec — one per feature.

Restarting a container is the supported way to bounce a feature without reloading the whole configuration, and it is far less disruptive than a config reload:

sudo systemctl restart bgp
sudo systemctl restart lldp
docker restart teamd
docker logs --tail 100 bgp

If a daemon refuses to start, the reason is almost always in its log or in the STATE_DB entry that reports container health. Check both before editing anything.

User Management

sudo useradd -s /bin/bash -m -G sudo,docker,redis <user>
sudo passwd <user>

Users are managed with standard Linux commands; adding a user to the sudo,docker,redis groups gives them admin-equivalent access to the switch.

Because of that, group membership is the access-control boundary on SONiC and deserves the same care you would give a privileged role on any server. Restrict sudo to a small operations group, avoid shared accounts entirely, and prefer SSH keys with PasswordAuthentication no in /etc/ssh/sshd_config. Auditing who did what is a matter of reading /var/log/auth.log, since there is no separate configuration-change log.

Logs and Troubleshooting Entry Points

show logging                     # syslog buffer
sudo tail -f /var/log/syslog     # live system log
docker logs swss --tail 50       # orchagent and friends
docker logs syncd --tail 50      # ASIC programming
sonic-db-cli STATE_DB KEYS 'SYSLOG*'
cat /host/reboot-cause/previous/boot_cause 2>/dev/null

The layering pays off here: a configuration that the CLI accepted can still fail in the orchagent. If config returns success but the interface never comes up, the answer is in swss logs, not in CONFIG_DB. Conversely, if the CLI itself rejects a command, the syntax or the platform capability is at fault, and no amount of database inspection will help. Diagnosing which layer to look at is the central skill of SONiC troubleshooting, and our SONiC CLI configuration guide walks through more of the command surface.

Image Management and Upgrades

sudo sonic-installer list                    # installed images and default
sudo sonic-installer install /tmp/sonic.bin  # install a new image
sudo sonic-installer set-default SONiC-OS-202411
sudo sonic-installer cleanup                 # remove unused images
sudo reboot

SONiC uses an A/B image layout: installing a new image does not disturb the running one, and switching the default followed by a reboot boots into it. Rollback is simply setting the default back to the previous image and rebooting, which is why upgrades on SONiC are far less anxious than on a traditional NOS. Always back up /etc/sonic/config_db.json before an upgrade, since a major version change can alter key schemas — our notes on config_db.json save, reload and replace cover the migration details.

Quick Runbooks

Bring up a new access port.

sudo config interface startup Ethernet12
sudo config mtu Ethernet12 9100
sudo config vlan member add -u 100 Ethernet12
sudo config save -y
show interfaces status Ethernet12

Investigate a port that shows down.

show interfaces status Ethernet12
sonic-db-cli STATE_DB hgetall 'PORT_TABLE|Ethernet12'
docker logs syncd --tail 50
sudo ethtool Ethernet12   # if the platform exposes it

If the state table shows down but the peer expects up, the fault is almost always physical — optics, cable, or an MTU mismatch on a tagged link. For packet-level verification, our Linux network troubleshooting guide covers ss, netstat and tcpdump, all of which are present on the switch.