SONiC Network OS User Manual: Install and Configure

SONiC (Software for Open Networking in the Cloud) is an open-source, Linux-based network operating system that runs on switches from several merchant-silicon vendors, and its BGP, RDMA and routing features are proven in hyperscale cloud data centers. This article condenses the essentials of the official SONiC user manual into a practical, start-to-finish handbook: image installation over ONIE or USB, first login and console behaviour, management interface and loopback configuration, how config_db.json stores every change, port and counter verification, packet-drop analysis, optical power reading, log collection, and how to safely isolate a device from the fabric. Treat it as the user manual you keep open while you commission a new switch and during your first weeks of operating it.

What SONiC Is and How This Manual Is Organised

SONiC is not a monolith. It is a collection of Docker containers — bgp, swss, syncd, pmon, teamd, database and others — coordinated through a Redis database called ConfigDB. Every CLI command you type ultimately writes a key into that database, and the daemons watching that key reconfigure themselves. Understanding this one design decision explains almost everything else about the platform: why configuration is not saved automatically, why some features need a container restart to take effect, and why the "CLI" behaves differently from IOS or Junos.

The rest of this manual follows the order in which you will actually need things: install, log in, address the box, configure ports, verify what you built, and troubleshoot when something does not come up.

Installing SONiC

ONIE Network Install

Bare-metal switches carry ONIE in a protected flash region. From the ONIE installer shell, address the management port and install over HTTP:

ONIE:/ # ifconfig eth0 192.168.0.2 netmask 255.255.255.0
ONIE:/ # ip route add default via 192.168.0.1
ONIE:/ # onie-nos-install http://192.168.2.10/sonic-broadcom.bin

The console baud rate for ONIE is 115200, while SONiC's Linux console commonly defaults to 9600 — if the screen goes blank right after the switch reboots, adjust the terminal rather than reinstalling. A switch that already runs a proprietary NOS must first be taken to ONIE: Uninstall OS and rebooted before ONIE: Install OS will accept the image.

USB Install

With no network path available, mount removable media and install from the local file:

ONIE:/ # mkdir -p /mnt/usb
ONIE:/ # mount -t vfat /dev/sdb1 /mnt/usb
ONIE:/ # onie-nos-install file:///mnt/usb/sonic-broadcom.bin

Arista Platform Install

Arista hardware boots through Aboot and needs a SWI image rather than a raw .bin. Install it the same way you would upgrade an EOS image:

localhost# copy http://192.168.2.10/sonic-aboot-broadcom.swi flash:
localhost(config)# boot system flash:sonic-aboot-broadcom.swi
localhost(config)# reload

The same sequence doubles as the recovery path for an Arista switch stuck in the Aboot shell, and the full walkthrough including prerequisites and troubleshooting lives in our SONiC ONIE install quick start.

First Login and Basic Access

Default credentials are admin / YourPaSsWoRd. Change the password as your first action, and decide immediately whether this switch will authenticate locally or against TACACS+/RADIUS. On the console, note that the login prompt appears only after the containers have started; a prompt that never appears usually means a container failed at boot rather than a failed installation.

admin@sonic:~$ show version
admin@sonic:~$ show hostname
admin@sonic:~$ docker ps

docker ps is the fastest single health check on a SONiC box: if bgp, swss, syncd and pmon are all Up, the platform itself is functional and any remaining problem is configuration rather than plumbing.

Configuring the Management Interface and Loopback

The management interface eth0 uses DHCP by default, which is convenient in a lab and almost always wrong in production. The supported way to pin a static address is a JSON snippet loaded into ConfigDB:

admin@sonic:~$ sudo config load mgmt_ip.json -y
# MGMT_INTERFACE: {"eth0|10.11.12.13/24": {"gwaddr": "10.11.12.1"}}

The key chain is worth reading carefully. MGMT_INTERFACE is the ConfigDB table, the field name is the interface name joined to the address with a pipe (eth0|10.11.12.13/24), and gwaddr carries the default gateway for that interface. Loopback addresses use the LOOPBACK_INTERFACE key with the same interface|address convention, which is what you want for a BGP router-id or an anycast service address that must survive a link flap.

To read back everything the box currently believes:

admin@sonic:~$ show runningconfiguration all
admin@sonic:~$ show ip interfaces
admin@sonic:~$ show ip route
admin@sonic:~$ show management_interface address

Remember that a config change only lives in Redis until you run sudo config save -y. Confirm your edits landed in /etc/sonic/config_db.json before you walk away; the full save, reload and replace workflow is documented in our SONiC config_db.json guide.

Daily Configuration: Ports, VLANs and Port-Channels

Front-panel ports are named Ethernet0, Ethernet4, Ethernet8 and so on, in steps of four because each port occupies a four-lane slice of the ASIC. A typical commissioning sequence looks like this:

admin@sonic:~$ sudo config interface ip add Ethernet0 10.0.0.1/24
admin@sonic:~$ sudo config interface startup Ethernet0
admin@sonic:~$ sudo config interface description Ethernet0 uplink-to-spine1
admin@sonic:~$ sudo config vlan add 10
admin@sonic:~$ sudo config vlan member add 10 Ethernet4
admin@sonic:~$ sudo config portchannel add PortChannel1
admin@sonic:~$ sudo config portchannel member add PortChannel1 Ethernet8
admin@sonic:~$ sudo config save -y

Two operational notes. First, config interface startup is what administratively enables a port after a shutdown; a port that is administratively down will not appear as up no matter how good the cable is. Second, LACP membership changes are disruptive for that port-channel — the member links bounce as teamd reprograms the bundle, so do it in a window on a live fabric.

Verifying Ports, Counters and Optical Power

Port Status and Counters

admin@sonic:~$ show interface status
admin@sonic:~$ show interfaces counters
admin@sonic:~$ show interfaces counters -a
admin@sonic:~$ show interface Ethernet12

Reading the counter columns correctly is the single most useful troubleshooting skill in SONiC:

• RX_ERR / TX_ERR — physical-layer errors: FCS failures, runts, alignment errors. A non-zero and growing value means a cable, optic or PCB trace problem, not a protocol problem.
• RX_DRP — packets dropped in the ingress pipeline, typically ACL, buffer or policy drops.
• TX_DRP — most often egress congestion and WRED discards; look at queue watermarks and PFC next.
• RX_OVR / TX_OVR — oversize frames, which point at an MTU mismatch between the two ends.

If you see congestion drops rather than errors, the diagnostic path continues in SONiC troubleshooting: packet drops and link issues and, for lossless fabrics, our SONiC PFC watchdog guide.

Optical Module Power Readings

admin@sonic:~$ show interfaces transceiver eeprom Ethernet12 --dom
admin@sonic:~$ show interfaces transceiver presence
admin@sonic:~$ show interfaces transceiver lpmode

The --dom flag reads the Digital Optical Monitoring page and prints TX and RX power for each lane. As a rule of thumb you want receive power better than −10 dBm; much below that and you will see intermittent link flaps as temperature drifts. Remember that AOC and DAC cables carry no DOM data — an empty reading on a copper or active optical cable is expected, not a fault. transceiver presence answers the earlier question of whether the module is even seated, and lpmode tells you whether low-power mode is holding a port down.

Isolating a Device Without Pulling Cables

When a switch misbehaves in a live fabric, the fastest way to remove it from the routing topology without losing console access is to drain its BGP sessions:

admin@sonic:~$ sudo config bgp shutdown neighbor SONIC02SPINE
admin@sonic:~$ sudo config bgp shutdown all

The first command takes a single peer out of service so you can compare behaviour; the second withdraws every session, which lets the fabric reconverge around the box while you keep the management IP and can finish your investigation. Bring the sessions back with config bgp startup all, and confirm with show bgp summary that every peer is back to Established before you leave.

Logging, Remote Collection and Support Bundles

Logs are the first place to look when a protocol session will not come up, and SONiC exposes them both per-container and aggregated:

admin@sonic:~$ show logging
admin@sonic:~$ show logging -f
admin@sonic:~$ docker logs bgp --tail 100
admin@sonic:~$ show techsupport

show logging tails the syslog stream aggregated from every container; docker logs bgp isolates a single daemon, which is usually faster when the symptom is clearly BGP-related. show techsupport produces a tarball with configuration, counters, logs and platform data — collect it before you open a vendor case rather than after a reload wipes the evidence.

Maintenance: Upgrade, Backup and Rollback

SONiC keeps the current and previous image, both of which can be listed and selected from the installer tooling:

admin@sonic:~$ sudo sonic-installer list
admin@sonic:~$ sudo sonic-installer install http://192.168.2.10/sonic-broadcom.bin -y
admin@sonic:~$ sudo sonic-installer set-default SONiC-OS-202311
admin@sonic:~$ sudo config save -y

Before any upgrade, copy /etc/sonic/config_db.json off the box — that single file is the entire declarative state of the switch, and restoring it after a rollback takes seconds. After a rollback, verify with show version and show interfaces status that the running image and port states match what you expect. A firmware decision that catches people out is covered in our ONIE versus in-place image install comparison.

Acceptance Testing and Handover

Before you hand a new SONiC switch to operations, run through a short acceptance pass. Confirm the management address survives a reboot, confirm that config_db.json contains the interfaces you configured, and confirm that every port you patched shows up/up in show interfaces status. Then check the counters are clean — zero errors on a freshly commissioned link is the baseline you want in your records, because it gives you something to compare against in three months when someone reports intermittent loss.

Two documents make the handover durable. First, the saved config_db.json itself, stored outside the switch so it can be restored after a failed upgrade. Second, a one-page record of the platform SKU, the image version, the port map and the expected BGP peer list — the four facts every future incident responder will ask for first. Our Dell S-Series SONiC basic management guide shows what that baseline looks like on a specific platform.

Common First-Week Problems

Four issues account for most of the questions a new SONiC operator asks:

• "My change disappeared after a reboot." You did not run config save -y. Redis held the change; config_db.json never learned about it.
• "Ports are missing from show interfaces status." The image does not match the platform, or the port is in admin-down state. Check show platform summary first.
• "The console is dead." Baud rate mismatch at 9600 versus 115200, in the great majority of cases.
• "Config reload took the whole rack down." config reload restarts nearly every container and interrupts forwarding — it belongs in a maintenance window, never on a live spine.

For hands-on practice before you touch hardware, our SONiC in GNS3 guide covers the virtual lab path, and Supermicro SONiC configuration basics covers a specific platform end to end.

原文链接：https://github.com/sonic-net/SONiC/blob/master/doc/user-manual/SONiC-User-Manual.md