SONiC Quick Start: Install via ONIE in Minutes

SONiC (Software for Open Networking in the Cloud) is the open-source, Linux-based network operating system that Microsoft runs at hyperscale and that a growing list of operators deploy on bare-metal switches from Dell, NVIDIA/Mellanox, Celestica, Edgecore and Arista. The good news for anyone evaluating it is that installation is not a long, license-driven process: a supported switch boots into ONIE, you hand it an image over HTTP, and a few minutes later you are logging into a working NOS. This guide walks the complete ONIE install workflow end to end — hardware prerequisites, image selection, the ONIE boot menu, network and USB installations, the special Aboot/SWI path used on Arista hardware, first login, and the Redis-backed ConfigDB model that governs how SONiC stores every configuration change.

What ONIE Is and Why It Matters

ONIE (Open Network Install Environment) is a small Linux-based bootloader that ships in the flash of most bare-metal switches. Its job is to standardize how a network operating system is discovered, installed and later recovered on merchant-silicon hardware. Before ONIE, every vendor had its own image format and its own recovery procedure; with ONIE, the switch firmware exposes a common installer that can pull a NOS image from HTTP, TFTP, USB or a local filesystem and write it to the boot partition.

The practical consequences are worth stating explicitly, because they are what make the SONiC model attractive:

• No vendor lock-in at the OS layer. The same switch can run SONiC today and a different NOS next quarter; reinstalling the OS is a bootloader operation, not a support contract negotiation.
• Zero-touch provisioning. ONIE can be pointed at an HTTP or TFTP server with an auto-discovery configuration, so a rack of switches can be imaged without a serial console session per unit.
• A predictable recovery path. If a SONiC image fails to boot, ONIE is still there in the protected flash region, so you can uninstall and reinstall the OS without an RMA.

That last point is the one that saves the most time in production. Most "SONiC is broken" incidents are actually "the image is wrong or the config is wrong", and both are recoverable from the ONIE menu in minutes.

Prerequisites: What You Need Before You Start

Before you touch a switch, confirm the following. Skipping any one of these is the most common reason an install stalls at the ONIE prompt.

• A supported switch platform. SONiC supports specific ASIC families (Broadcom Trident/Trident2/Tomahawk, Mellanox Spectrum, Cavium and a handful of others) plus a defined list of platforms. Check the supported-platforms list for your image release before you download.
• Serial console access. A USB-to-RJ45 console cable or serial adapter, 8N1, and the correct baud rate. ONIE's console runs at 115200 baud; the SONiC Linux console after install defaults to 9600 on many platforms. Keep both in mind.
• An HTTP (or TFTP/USB) staging point. The image is 500 MB to 1 GB depending on ASIC and release, so pick a server reachable from the management VLAN and verify the file is downloadable with curl -I before you start.
• Network information. A management IP for the switch during install, the subnet mask, and the default gateway toward the file server.
• A maintenance window. Installation wipes the switch. Never do this on a device carrying production traffic.

Download the Right Image

SONiC publishes one image per ASIC vendor, named after the platform it targets — for example sonic-broadcom.bin, sonic-mellanox.bin, or a platform-specific build such as sonic-broadcom.bin for Broadcom-based boxes. Download the image that matches your switch's ASIC; the wrong image will flash and then simply fail to boot, which is a confusing failure mode rather than an obvious error. You can also build a custom image from source with sonic-buildimage, which is how most vendors produce their branded distributions.

Two habits pay off here. First, verify the checksum of every image you download, especially if it travelled through a jump host. Second, keep at least one known-good image version on the staging server even after you upgrade — SONiC's installer keeps only the current and previous image on the switch, and having a third version on hand makes rollback trivial.

Booting the Switch Into ONIE

Connect to the switch over serial and power it on. If the switch already ships with a proprietary NOS, you will first see that NOS boot, not ONIE. The clean path is to enter the ONIE menu, choose ONIE: Uninstall OS, let it finish, reboot, and then choose the install entry. On a switch with no OS installed, the GRUB menu comes up directly:

GNU GRUB version 2.02~beta2+e4a1fe391
|*ONIE: Install OS    <----- Select this one
| ONIE: Rescue
| ONIE: Uninstall OS
| ONIE: Update ONIE
| ONIE: Embed ONIE

The menu entries have specific meanings, and knowing them prevents a lot of head-scratching:

• ONIE: Install OS — boots into the ONIE installer environment and, if auto-discovery is configured, immediately tries to find a NOS image.
• ONIE: Rescue — a shell with the installer available but no auto-discovery, useful for one-off manual installs like the HTTP example below.
• ONIE: Uninstall OS — wipes the NOS partition set; required before installing a different NOS on a switch that already runs one.
• ONIE: Update ONIE — refreshes the bootloader itself, typically for a firmware CVE or a new platform revision.
• ONIE: Embed ONIE — writes ONIE into the flash for the switch, the recovery-of-last-resort option.

Auto-discovery can be noisy on a busy management segment because every ONIE switch listens for DHCP option 114 and will try to install whatever it is offered. On a production management VLAN, either suppress the discovery server or use the Rescue console path for manual installs.

Step 1 — Give ONIE an Address

At the ONIE:/ # prompt, bring up the management interface and route ONIE toward your file server. On most platforms the first onboard port is eth0:

ONIE:/ # ifconfig eth0 192.168.0.2 netmask 255.255.255.0
ONIE:/ # ip route add default via 192.168.0.1

If the platform supports DHCP on the management port, udhcpc -i eth0 is faster than typing a static address. Either way, confirm connectivity before starting the install — a failed transfer halfway through a 700 MB image leaves you back at the ONIE prompt with nothing to show for the wait:

ONIE:/ # ping -c 3 192.168.2.10
ONIE:/ # wget -O /dev/null http://192.168.2.10/sonic-broadcom.bin

Step 2 — Install Over HTTP with onie-nos-install

With reachability confirmed, launch the installer against the image URL:

ONIE:/ # onie-nos-install http://192.168.2.10/sonic-broadcom.bin

ONIE downloads the image, validates it, writes it to the NOS partitions, updates the GRUB configuration, and reboots the switch. Depending on platform and image size this takes roughly five to fifteen minutes. When installation finishes, the switch boots into SONiC automatically — you do not need to change the GRUB default entry by hand.

The same command works with other transports; ONIE understands a scheme prefix on the URL, so tftp://, ftp://, file:///mnt/usb/ and even scp:// style local paths are all valid depending on how the bootloader was built. For lab work, a laptop running Python's built-in HTTP server on the directory holding the image is usually the fastest staging option.

Step 3 — USB and Local Media Installs

When there is no network path to the switch — a greenfield rack with no management VLAN yet, or an isolated lab — install from removable media. Format a USB stick as FAT32, copy the image onto it, plug it in, and from the ONIE shell mount it and point the installer at the file:

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

The device name varies by platform (/dev/sda1, /dev/sdb1, occasionally /dev/sdc1), so check cat /proc/partitions or dmesg | tail after plugging the stick in rather than guessing. Using onn or onie-nos-install with a file:// URL is the standard approach.

Installing SONiC on Arista Hardware

Arista switches do not boot through ONIE in the usual way; they use the Aboot bootloader and expect a SWI-format image instead of a raw .bin. Install it exactly the same way you would upgrade an EOS image:

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

The copy command pulls the SWI onto flash, boot system sets it as the next boot image, and reload reboots into it. Note the image naming: on Aboot you need the sonic-aboot-broadcom.swi build, not the generic sonic-broadcom.bin — the generic image is not bootable from Aboot.

These same steps are also the standard recovery procedure for an Arista switch stuck in Aboot, for example after the boot-config file was removed or a failed upgrade left no valid image. In the Aboot shell, use udhcpc to pick up an address over DHCP, or configure a static IP manually, then fetch the SWI and repeat the sequence above.

First Boot: Login, Console and Verification

Once the switch reboots into SONiC, log in on the console with the factory credentials admin / YourPaSsWoRd and change the password immediately — public default credentials on a switch that is about to be cabled into a production network are a real risk, not a formality.

If the console shows nothing after the reboot, the most likely cause is the baud rate. SONiC's Linux console default is 9600 for many images while ONIE runs at 115200, so adjust your terminal client rather than assuming the install failed. Then confirm the basics from the shell:

admin@sonic:~$ show version
admin@sonic:~$ show platform summary
admin@sonic:~$ show interfaces status
admin@sonic:~$ show system health

A healthy freshly installed switch shows the expected platform and ASIC, every front-panel port in an up or down administrative state (not missing), and no failed containers. If ports are absent from show interfaces status entirely, you very likely flashed the wrong ASIC image.

How SONiC Configuration Works: ConfigDB

SONiC manages configuration in a single source of truth — a Redis database instance called ConfigDB. Applications subscribe to ConfigDB and generate their running configuration accordingly, which is what enables the modular, containerized architecture where each protocol daemon (bgp, swss, syncd, pmon) runs in its own container and reacts to database changes rather than to direct CLI edits. The old minigraph.xml method predates September 2017 and is kept only for historical reference.

Two consequences follow directly from that design, and both bite newcomers. First, the running configuration lives in Redis and is not automatically written to disk — config save -y is what persists the current state to /etc/sonic/config_db.json, and without it a reboot quietly loses your work. Second, you can inspect and even modify the database directly, which is invaluable when a CLI command does not exist yet for the feature you need:

admin@sonic:~$ sudo config save -y
admin@sonic:~$ sonic-cfggen -d --print-data
admin@sonic:~$ redis-cli -n 4 keys '*'
admin@sonic:~$ redis-cli -n 4 hgetall 'VLAN|Vlan10'

The deeper mechanics of saving, loading and replacing the database — and the failure modes you can create by editing it by hand — are covered in our SONiC config_db.json save, reload and replace guide.

Troubleshooting Failed ONIE Installs

Most failures fall into four buckets, and each has a distinct symptom:

• Download failure. ONIE reports an HTTP error or hangs during transfer. Check the URL from a workstation on the same subnet, confirm the file server is not rate limiting, and re-run with wget first to separate network problems from installer problems.
• Image/platform mismatch. The install completes but the switch will not boot, or after boot the ports are missing. Re-download using the platform-specific image name for your exact hardware SKU.
• Existing NOS still present. ONIE refuses to install over an existing OS or boots straight back into the old NOS. Choose ONIE: Uninstall OS, reboot, then install.
• Console is silent after reboot. Almost always the 9600 versus 115200 baud mismatch described above — check that before you start pulling cables.

When an install is truly wedged, ONIE Rescue plus a fresh download is faster than debugging the old image: the bootloader is deliberately designed to be the last thing standing, so it is nearly always still usable.

Where to Go Next

Once the switch is up, the priorities are the management IP, an interface configuration that matches your cabling, and BGP if you are building a fabric. To practice the whole flow without hardware, see our SONiC configuration in GNS3 guide; for a real hardware walkthrough on a budget 25GbE/100GbE box, read Install SONiC on Dell S5212F-ON. If you are coming from a vendor NOS, the switch-side command mapping in our MLNX-OS port types article and the automation path in NVIDIA Air + Ansible with Git are useful complements. And when the first link comes up and the counters look wrong, SONiC troubleshooting: drops, optics and techsupport picks up exactly where this guide stops.

原文链接：https://github.com/sonic-net/SONiC/wiki/Quick-Start