SONiC config_db.json: Persistence, Save and Rollback

SONiC does not behave like a traditional network operating system when it comes to saving configuration, and that trips up engineers who expect write memory semantics. Configuration lives in a Redis database called CONFIG_DB, while the startup configuration is a JSON file at /etc/sonic/config_db.json. Changes made through the CLI land in the running configuration immediately but disappear on reboot unless you explicitly save them. This article explains the model, shows the save and reload workflow, and gives a rollback procedure that does not require console access.

The two-layer configuration model

Because the ASIC programming path is driven by CONFIG_DB, a change can be visible in show running-configuration without being visible to the hardware for a short period. When verifying, always check both the configuration view and the operational view.

Making changes that survive a reboot

admin@switch:~$ sudo config vlan add 100
admin@switch:~$ sudo config vlan member add -u 100 Ethernet12
admin@switch:~$ sudo config vlan member add -u 100 Ethernet16
admin@switch:~$ sudo config save -y

Without the config save step the VLAN exists in memory only. This is the single most common SONiC operational mistake: a change is tested, appears to work, and vanishes during the next maintenance reboot, which then looks like a hardware or firmware problem.

Reading the configuration

admin@switch:~$ show runningconfiguration all
admin@switch:~$ show runningconfiguration interfaces
admin@switch:~$ show runningconfiguration bgp
admin@switch:~$ show vlan brief
admin@switch:~$ sudo cat /etc/sonic/config_db.json

show runningconfiguration all dumps the effective CONFIG_DB content, which is the authoritative view of what the switch is currently running. The JSON file on disk is the startup view and will differ after unsaved changes.

Minimal config_db.json structure

{
  "DEVICE_METADATA": {
    "localhost": { "hostname": "leaf-01" }
  },
  "VLAN": {
    "Vlan100": { "vlanid": "100", "mtu": "9216" }
  },
  "VLAN_MEMBER": {
    "Vlan100|Ethernet12": { "tagging_mode": "untagged" },
    "Vlan100|Ethernet16": { "tagging_mode": "untagged" }
  },
  "INTERFACE": {
    "Ethernet0": {},
    "Ethernet0|10.10.10.1/31": {}
  }
}

Editing JSON directly is supported and often the fastest way to apply a templated configuration: write the file, then load it. The table names are schema-defined, so validate against the SONiC configuration schema for your release rather than guessing keys.

Reloading and rolling back safely

# Keep a copy of the working configuration before any change
admin@switch:~$ sudo cp /etc/sonic/config_db.json /etc/sonic/config_db.json.bak

# Load a specific configuration file
admin@switch:~$ sudo config load -y /etc/sonic/config_db.json.bak

# Reboot to apply with a clean state
admin@switch:~$ sudo reboot

config load replaces CONFIG_DB with the file contents, which makes the backup file your rollback mechanism. Two rules make it usable in anger:

• Save a copy (with the date) immediately before every change, and keep the last known-good copy somewhere off the switch.
• Test a reload on one member of a fabric, not on the whole fabric at once — config load does not merge, it replaces, so any key missing from the file disappears.

Recovering a switch that will not come back

If a load leaves the switch unreachable, the console gives you a Linux shell rather than a network CLI, which is an advantage: mount or scp a known-good config_db.json, or start from an empty configuration and re-apply management networking.

admin@switch:~$ sudo config reload -y
admin@switch:~$ sudo config interface ip add eth0 10.10.10.20/24 10.10.10.1
admin@switch:~$ sudo config save -y

Getting the management interface back is the first priority; everything else can be re-applied once you can reach the box over the network again.

Versioning SONiC configuration

Because the configuration is a JSON file, it fits standard version control better than most NOS configurations. A practical workflow:

1. Export config_db.json after every accepted change and commit it to the same repository as your templates.
2. Render per-switch files from a template with the hostname, loopback and port mapping as variables.
3. Apply with config load plus a controlled reboot, or through your orchestration layer.
4. Diff the exported file against the intended state in CI to detect drift.

Pitfalls summary

• Forgetting config save — changes lost at the next reboot.
• Assuming config load merges — it replaces the whole database.
• Editing JSON with invalid keys — the entry is ignored silently and the feature never programmes the ASIC.
• Verifying only with show runningconfiguration and not with operational commands such as show interfaces status or show vlan brief.
• Treating CONFIG_DB as the whole picture — state tables, APP_DB and ASIC_DB are separate Redis databases, and troubleshooting often means looking at all of them.

Troubleshooting: the change never reached the data plane

SONiC's layered architecture means a change can be accepted by the CLI, stored in CONFIG_DB, and still not appear in the hardware. Work down the layers rather than restarting services at random.

admin@switch:~$ show techsupport
admin@switch:~$ sudo generate_dump
admin@switch:~$ docker ps -a
admin@switch:~$ redis-cli -n 4 hgetall "VLAN|Vlan100"    # CONFIG_DB

The Redis databases are numbered by convention: CONFIG_DB is database 4, APPL_DB is 0, and ASIC_DB is 1. Comparing the same key across them is the fastest way to tell a configuration problem from an agent problem. If CONFIG_DB has the VLAN and APPL_DB does not, the orchagent or a feature container is the fault domain, not your CLI syntax.

How SONiC persistence compares with other network operating systems

The SONiC model is the most automation-friendly of these, because the startup configuration is a structured file that can be templated and versioned. It is also the least forgiving to interactive operators, because forgetting the save step silently discards work at the next reboot. Document the two-step discipline conspicuously in runbooks used by anyone who logs into the switch interactively.

Related SONiC articles

Start with the SONiC CLI configuration guide for command syntax, keep the SONiC show/config cheatsheet handy for daily operations, and use the SONiC troubleshooting guide when a change does not reach the data plane.

原文链接：https://netbergtw.com/top-support/netberg-sonic/configuring-sonic-using-cli-or-editing-json/