Your Cart

ONIE Guide for Installing a Network Operating System

Guide By
Engineers at a desk with a terminal open on a monitor, a laptop and a keyboard.

If you are buying a bare-metal switch and plan to install the network operating system yourself, you will likely come across ONIE. It stands for Open Network Install Environment and comes preinstalled on many bare-metal switches. Once you have chosen a version of SONiC or another operating system your switch supports, ONIE finds and runs the installer.

A switch can download a community SONiC image such as sonic-broadcom.bin and still stop at a warning that the image is for a different ASIC. That warning appears when the switch's platform identifier is missing from the image's platform list.

Forcing the installation gets past this warning without adding support for the switch's hardware. ONIE, the Open Network Install Environment, finds and runs the installer, but the image still has to support the switch. At the ASIC warning prompt, y or Y forces installation, n or N exits, and any other input makes the installer ask again. Do not force an image built for a different ASIC.

The Switch and NOS Must Match

For an ONIE installation, order a white box switch variant supplied with ONIE. ONIE and non-ONIE versions can use different EEPROM formats and contents.

Choose the SONiC distribution and release for the switch's platform and required port layout. The SONiC supported platforms page is a starting point. Filenames such as sonic-broadcom.bin and sonic-mellanox.bin identify SONiC builds for different ASIC families. For ARM builds, a filename can also include the CPU architecture, as in sonic-marvell-prestera-arm64.bin.

Arista platforms that SONiC supports and that use Aboot need an Aboot SWI image such as sonic-aboot-broadcom.swi. Check whether the delivered switch uses ONIE or Aboot before downloading an installer.

NVIDIA Cumulus Linux 5.18 has its own ONIE installation procedure. With Cumulus Linux 4.4 and later, you must hold a license for each switch, but you no longer enter a license key. If you need help matching a switch and NOS release, you can reach out to our engineers.

How the Switch Boots ONIE

ONIE uses Linux and BusyBox on the management CPU to reach storage and the management network. The management CPU can operate independently of the switching ASIC. ONIE uses the management port to download the installer.

On legacy BIOS x86 systems, the ONIE-BOOT partition holds ONIE's kernel and initial filesystem. The NOS installs the boot loader that starts the switch after installation. A NOS that uses GRUB can add an ONIE menu entry that chainloads the GRUB loader in that partition.

On x86 UEFI systems, the EFI System Partition holds the EFI boot files. ONIE's kernel and initial filesystem remain in ONIE-BOOT. The NOS installs a separate EFI loader, and firmware boot entries select the NOS or ONIE. A GRUB-based NOS can also offer an ONIE chainload entry.

The ARM and PowerPC U-Boot designs normally store ONIE in NOR flash. The NOS installer sets nos_bootcmd to start the installed system on later boots. If that boot command fails or returns, U-Boot falls through to ONIE.

After a NOS installer sets up normal boot, the switch starts the NOS without running ONIE's installation environment. The boot menu or a command in the NOS can return the switch to ONIE. In ONIE's menu, Install OS searches for and runs a NOS installer, while Rescue opens a shell without starting that search. Disk names, partition numbers and storage layouts depend on the platform.

After a NOS installer sets up normal boot, the NOS boot entry starts the installed NOS. ONIE Install OS finds and runs a NOS installer and reboots only on success. ONIE Rescue opens a shell without automatic installer discovery. Update, Embed and Uninstall are separate menu choices outside these paths.After the NOS installer sets up normal bootNOS boot entryInstalled NOSONIE: Install OSFind and runa NOS installerReboot on successONIE: RescueONIE shellNo automatic discovery
On a GRUB-based x86 switch, Install OS runs an installer while Rescue opens an ONIE shell without automatic discovery.

The ONIE Menu Chooses What Happens Next

The ONIE GRUB menu selects installation, inspection, erasure or an ONIE update. Rescue gives you a shell for checking the switch before running an installer. Vendor diagnostic entries can appear too.

Menu entryAction
ONIE: Install OSFind and run a NOS installer
ONIE: RescueOpen a shell without discovery
ONIE: Uninstall OSErase the NOS and other unprotected data
ONIE: Update ONIEFind and run an ONIE updater
ONIE: Embed ONIEFind and run an ONIE updater in Embed mode

In ONIE's GRUB menu, Install OS can run an installer as soon as ONIE finds one. ONIE's installed-NOS flag is called NOS mode. With no saved mode request, the menu defaults to Install OS until that flag is set, then to Rescue. Selecting Install OS from that menu does not change the default.

A NOS can also save an Install OS request in ONIE's boot settings. With NOS mode set, that request selects Install OS for the next ONIE boot and ONIE clears it when that boot starts. If NOS mode remains set and no new request is saved, a later return to ONIE defaults to Rescue. Uninstall OS preserves ONIE and diagnostic partitions that meet ONIE's protection rules. Embed ONIE recreates the x86 disk layout and erases the disk's contents.

How ONIE Finds an Installer Automatically

In Install OS mode, discovery searches for an installer, downloads it and runs it. A failed attempt can lead to another search method. While discovery runs, ONIE repeats the search until installation succeeds.

For ONIE 2026.08 without a developer-supplied install_url kernel argument, ONIE looks for a NOS installer in the order below. On x86_64 systems using GRUB, ONIE checks for previously staged firmware packages before trying those sources. During an Install OS boot, ONIE rejects a queued updater image, logs the failure and continues with NOS installer discovery. Automatic local-storage discovery can find a USB installer only at the root of a mountable partition, under one of ONIE's default installer names. DHCP option 125 can supply an ONIE installer URL, and option 114 can supply an installer URL.

OrderInstaller source
1Local storage
2DHCP 125 installer URL
3DHCP 114 installer URL
4HTTP, then DHCP 67 URL
5TFTP boot files
6TFTP fallback paths

The install_url kernel argument lets developers supply an image URL directly. With that argument set, ONIE skips the local-storage and DHCP installer-discovery steps, while still discovering neighbors. If the URL fails, ONIE continues to the HTTP, TFTP and waterfall searches. HTTP can still use onie-server and management-link neighbors, and the TFTP waterfall can still use onie-server.

For HTTP searches using default installer filenames, ONIE first tries onie-server, then web-server addresses from DHCP option 72 and the BOOTP next-server address. Next come the DHCP server address from option 54, a TFTP server address from option 150 if received, and the TFTP server name from option 66. IPv4 and IPv6 neighbors come last. Neighbors are hosts found on the same management link, and the search does not cross a gateway.

Each server must accept a TCP connection on port 80 before ONIE tries default installer names over HTTP. After those attempts, ONIE tries option 67 as a URL. A full URL can specify a different port.

For TFTP boot files, ONIE tries onie-server, BOOTP next-server, option 66 for the TFTP hostname, option 150 for a TFTP address if supplied, then option 54 for the DHCP server. ONIE tries every received boot filename with each server. The filenames come from DHCP option 67 and the BOOTP file field.

The final TFTP fallback is called the waterfall. ONIE first tries a directory named for the management MAC address. In ONIE 2026.08, the address uses hyphens between octets and keeps its original letter case. Match the directory's case to the attempted URL in /var/log/onie.log. If DHCP supplied an IPv4 address, ONIE then tries eight directories based on that address in uppercase hexadecimal, removing the final hexadecimal digit for each successive directory.

Inside each MAC or IPv4 directory, ONIE looks for onie-installer-<platform> without a .bin extension. At the server root, ONIE then tries all default names and their .bin alternatives.

The waterfall searches onie-server, BOOTP next-server, the option 66 TFTP hostname and any option 150 TFTP address. The option 54 DHCP server address is used in the earlier boot-file attempts but not in the waterfall. A TFTP timeout ends the waterfall attempts for that server.

HTTP is the preferred transport for large installer files. To troubleshoot discovery, read /var/log/onie.log for the URLs the installed ONIE version actually attempted.

ONIE Searches a Fixed List of Installer Filenames

For local storage and HTTP searches, and at the TFTP server root, ONIE tries default names from the most specific platform match to the most general. Each name is tried without an extension and then with .bin.

onie-installer-<platform>
onie-installer-<platform>.bin
onie-installer-<arch>-<machine>
onie-installer-<arch>-<machine>.bin
onie-installer-<machine>
onie-installer-<machine>.bin
onie-installer-<arch>-<silicon>
onie-installer-<arch>-<silicon>.bin
onie-installer-<arch>
onie-installer-<arch>.bin
onie-installer
onie-installer.bin

Use onie-sysinfo -p for <platform> and onie-sysinfo -m for <machine>. The CPU architecture comes from onie-sysinfo -c. The <silicon> value comes from onie-sysinfo -S, with identifiers such as bcm or mvl.

The .bin alternatives were added in ONIE 2017.08, and the architecture plus silicon-vendor fallback was added in 2016.05. Older versions search fewer names. Update and Embed modes use the prefix onie-updater instead of onie-installer. A matching filename helps ONIE find the installer, but the image still has to support the switch platform.

DHCP Can Supply the Installer URL

ONIE identifies itself in DHCP requests so the server can choose an installer for the platform. Option 60 contains onie_vendor: followed by the platform string. Option 77 contains onie_dhcp_user_class, and option 61 carries a serial-based client identifier.

ONIE's enterprise number within DHCP option 125 is 42623. In ONIE's request, suboptions 3, 4 and 5 carry the machine, CPU architecture and revision. The DHCP server can return an image URL in option 125 under that enterprise number.

Within DHCP option 125, response suboption 1 supplies an image URL accepted in Install, Update and Embed modes. Response suboption 2 supplies an updater URL accepted only in Update or Embed. In Update and Embed, if the response contains both suboptions, ONIE uses whichever URL it parses last in that response. A complete DHCP image URL can point to the installer's existing filename, without renaming the file to a default ONIE name.

DHCP also supplies the address, subnet mask, gateway and DNS settings. During installer discovery, ONIE 2026.08 explicitly requests options 7, 43, 54, 66, 67, 72, 114 and 125, in addition to the DHCP client's default requests. These include log-server addresses, vendor-specific information, the DHCP server address, a TFTP server name, a boot filename, web-server addresses and the two installer-URL options.

Option 150 contains a TFTP server address, but ONIE 2026.08 does not request it. ONIE can use that address only if the DHCP server sends option 150 without being asked. BOOTP next-server supplies a server address independently of options 66 and 150. Hostnames, including a server name in option 66 and onie-server, require working name resolution.

ONIE uses option 114 for an image URL, while RFC 8910 assigns that code to captive portals. Send an ONIE image URL in option 114 only to ONIE clients, for example by matching their vendor class. If the DHCP server supports ONIE's option 125 suboption 1, use that option for the installer URL so ordinary clients do not receive it as a captive portal setting.

Secure Boot Comes Before Installation

On supported x86 UEFI systems, ONIE can boot through a Microsoft-signed shim, a GRUB loader signed by the switch manufacturer and a kernel signed by that manufacturer. Firmware must trust the shim, which carries the switch manufacturer's certificate.

The NOS needs boot files accepted by the switch's Secure Boot configuration. For Cumulus Linux 5.18 upgrades on Secure Boot switches (Spectrum-4 and later, or SN3700-S), NVIDIA requires ONIE installer version 5.3.0013 or later. NVIDIA's 5.18 installation page names SN3700C-S, while its upgrade page uses SN3700-S. If the switch has version 5.3.0012 or earlier, upgrade the ONIE installer first. NVIDIA's prescribed ONIE upgrade reloads and factory-resets the switch, so complete the backup and recovery preparations below before upgrading ONIE. These are NVIDIA's installer version numbers.

For Cumulus Linux 5.18 on NVIDIA switches with Secure Boot, disable Secure Boot before installing an unsigned Cumulus image. With Secure Boot enabled on those switches, you must log in to get an ONIE shell.

A Backup and Console Come First

Copy the existing switch configuration and any files you need to keep to another system before reinstalling. Complete that backup before any required uninstall step. Leave a serial console connected through installation and the first boot so errors remain visible if management access fails.

When reinstalling or upgrading Cumulus Linux 5.18 with ONIE, back up configuration off the switch and keep original certificates and certificate revocation lists (CRLs) available to reimport before any ONIE installer upgrade or NOS image installation. For a switch configured with NVIDIA User Experience (NVUE), review "What's New" for new NVUE syntax and other configuration changes before backing up and restoring configuration across releases. Snippets and flexible snippets can become invalid. If the new release introduces NVUE syntax for a feature configured by a snippet, remove that snippet before upgrading. Save the NVUE configuration with nv config save, then copy /etc/nvue.d/startup.yaml and its referenced certificate files off the switch before either destructive step. After installing Cumulus Linux, restore those certificate files to their original paths and reimport certificates and CRLs with each certificate's original certificate-id. For a manual configuration restore, copy startup.yaml back and translate it for the new release if required. Run nv config replace with that file, then nv config apply. When starting the installation from running Cumulus Linux, onie-install -t stages startup.yaml with the image so the new release preserves and automatically translates the NVUE configuration. The installation does not back up or automatically restore certificates and CRLs. Features that need certificates remain unavailable until reimport.

Have a recovery method for your exact switch ready before erasing storage or changing the boot environment. ONIE recovery ISOs use GRUB and must match the switch's ONIE machine type, revision and CPU architecture. They do not provide recovery for U-Boot switches. USB boot requires firmware support. Rescue starts ONIE from the recovery media. On x86, Embed repartitions and formats the disk, erasing the NOS. A NOS installer alone cannot start ONIE when ONIE itself will not boot. If you need help with recovery, the console cable, pinout or serial settings, you can reach out to our engineers.

The console cable, pinout and serial settings depend on the switch. ONIE's default rate is 115200 baud, although the platform can use another rate. The NOS may also use a different rate from ONIE. If the console becomes unreadable when the new NOS starts, set your terminal program to that NOS's serial settings.

Rescue Allows a Manual Installation

Interrupt boot at the GRUB menu through the serial console. A switch without a NOS may already show the ONIE menu. If the NOS has an entry named ONIE, select that entry to reach ONIE's menu, then select ONIE: Rescue.

A running NOS may have a command to reboot into Rescue. On a BIOS switch without that command, the GRUB method requires grub-reboot and a NOS menu entry named exactly ONIE. Mount ONIE-BOOT read-write at /mnt/onie-boot, then run grub-reboot ONIE. Run /mnt/onie-boot/onie/tools/bin/onie-boot-mode -o rescue before rebooting.

The UEFI method also needs ONIE-BOOT mounted read-write. Use efibootmgr to find ONIE's firmware boot number. Remove the Boot prefix and any trailing * from that hexadecimal number, then use the number with efibootmgr --bootnext to select ONIE for the next boot. Run /mnt/onie-boot/onie/tools/bin/onie-boot-mode -o rescue before rebooting.

On U-Boot platforms, the NOS can set onie_boot_reason to rescue before rebooting. At the U-Boot prompt, run onie_rescue starts Rescue directly.

Press Enter at ONIE's console activation prompt. Rescue starts without automatic installer discovery, which is ONIE's search for an installer. If you entered Install OS instead, stop discovery before changing the management address.

onie-stop

ONIE 2018.05 and later provide onie-stop. If the shell reports that command is not found, run onie-discovery-stop. ONIE 2026.08 still accepts the older command as a deprecated alias. Stopping discovery also ends an in-flight download or installer, so use the stop command before starting your manual installation. After stopping it, recurring search messages should cease and the shell should accept commands.

ONIE Identifies the Platform

Read the ONIE version, machine, revision and CPU architecture before choosing the installer. The commands below print those values individually, followed by the platform string.

onie-sysinfo -v
onie-sysinfo -m
onie-sysinfo -r
onie-sysinfo -c
onie-sysinfo -p

The usual platform string has the form <arch>-<machine>-r<revision>. Copy the exact machine and platform values printed by ONIE when matching an image to the switch. Machine names normally include the switch manufacturer's name.

ONIE 2019.05 and later also provide onie-sysinfo -l to report bios, uefi or u-boot. On older versions, identify the boot method from the switch's boot menu and hardware instructions.

The Management Port Reaches the Server

Connect the management port to the installation network and stay in Rescue, or leave discovery stopped, while setting the address. Default ONIE builds allow SSH and telnet without a password. Isolate the installation network from production and user networks while ONIE runs.

Place the chosen installer on an HTTP server. From another machine, download the file using the URL you will give ONIE. Compare its checksum with the image provider's published value when available.

Inspect the switch's address and route first. If DHCP has already supplied an address and a working route to the server, leave that configuration in place. In ONIE 2026.08, eth0 falls back to a link-local address in 169.254.0.0/16 only after static configuration, DHCPv6 and DHCPv4 all fail. ONIE does not assign an address when the link is down. That fallback address is not a DHCP lease and will not reach the routed HTTP server in the example below.

ifconfig eth0
ip route

In this static-address example, eth0 uses 192.168.0.2/24 and the gateway is 192.168.0.1. The HTTP server is on another subnet at 192.168.2.10. Use the interface, addresses, mask and gateway for your installation network, with an address that no other device uses. The commands assume there is no existing default route. If DHCP already provides a working route, keep it and skip these commands.

ifconfig eth0 192.168.0.2 netmask 255.255.255.0
ip route add default via 192.168.0.1

Run ifconfig eth0 and ip route again. The address should be 192.168.0.2, the mask 255.255.255.0 and the default gateway 192.168.0.1. The gateway must reach the server, and the server needs a route back to the switch. A hostname in the installer URL also needs working DNS.

serial consoleswitcheth0 192.168.0.2/24gateway192.168.0.1HTTP server192.168.2.10management network
The switch reaches the HTTP installer server through its management interface and a gateway.

The Installer Runs from the URL

From the ONIE Rescue shell, run onie-nos-install with the image URL. The command also works in Install OS mode and stops discovery before running the installer. The example requires a switch supported by the selected Broadcom SONiC image.

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

Watch the console through installation and the reboot. ONIE reboots after a successful NOS installation. If SONiC asks whether to force an image for a different ASIC, decline and check that the image supports the platform reported by ONIE.

Log in with the credentials for the selected image. Community SONiC defaults to user admin and password YourPaSsWoRd unless the image was built with different credentials. Set a new password at first login.

show version
show platform summary

show version reports the release and build information, along with Platform and HwSKU. show platform summary also reports Platform and HwSKU, with chassis identifiers such as Serial Number, Model Number and Hardware Revision where available.

HwSKU is the SONiC profile selected in CONFIG_DB, including the port layout. The value identifies the configured profile rather than a detected commercial part number. Before restoring configuration, compare the release and Platform with the chosen image. Confirm that the configured HwSKU provides the port layout required for your switch.

A Failed Installation Can Be Inspected in Rescue

Rescue lets you read errors without automatically starting another installation. The ONIE log records the URLs attempted and the installer activity in the current ONIE session. ONIE 2026.08 writes this log in its runtime filesystem, so a reboot into Rescue may leave you without the earlier attempt's log. Copy the log to another system or save the console output before rebooting.

cat /var/log/onie.log

Read the current session's last failure and the messages around it to distinguish a failed download from an error after the installer starts. After a reboot, use a saved log or console capture from the failed attempt if you have one. Correct the cause before trying the installation again. If ONIE itself cannot start, another NOS download will not restore ONIE. Pause the NOS replacement and reach out to our engineers before attempting boot-firmware recovery.

Uninstall Can Erase Data Beyond the NOS

Back up the configuration and other files you need before selecting ONIE: Uninstall OS. Uninstall erases the NOS and other unprotected data on the target storage. Complete the recovery preparations above before starting.

The ONIE 2026.08 x86 uninstall script overwrites and deletes partitions on the disk containing ONIE, with specific exceptions. On GPT disks, the protected partition types are EFI System, GRUB and ONIE-BOOT. A diagnostic partition is protected when its name ends in -DIAG and its attribute flags equal 0000000000000001.

In ONIE 2026.08, x86 builds default to GPT unless configured for MSDOS. On MSDOS disks, Uninstall protects partitions by checking labels for ONIE-BOOT or -DIAG. On eMMC and NVMe, the check omits the p before the partition number and can miss those labels. On x86 with MSDOS on either device, this can erase ONIE-BOOT and prevent ONIE from booting. Under UEFI, Uninstall preserves EFI/onie, directories ending in -DIAG and the fallback directory EFI/BOOT, and removes the other directories under EFI. Uninstall also removes stale UEFI boot entries and moves the existing ONIE entry to the front of the boot order. Under BIOS, uninstall reinstalls ONIE's GRUB in the MBR.

The ONIE 2026.08 U-Boot uninstall script can erase the NOR-flash area exposed as /dev/mtd-open and the U-Boot environment when those devices exist. Its disk erase targets the fixed storage device named by /proc/device-tree/mass_storage/device, when present. With an MSDOS partition table, partitions identified by ONIE-BOOT or -DIAG labels are skipped only when their device names need no p separator. In ONIE 2026.08, that label check fails on eMMC and NVMe, so labelled partitions can be erased. The GPT diagnostic-partition rule also applies on U-Boot platforms. A device without partitions is overwritten whole. ONIE itself is preserved.

Allow disk overwriting to finish, which can take time on a large disk. A successful uninstall reboots into installer discovery, so the next boot can start another installation automatically.

Updating ONIE and Embedding It Are Different

Choose an ONIE updater built for the switch's exact machine, revision and CPU architecture. Run onie-self-update from Rescue or Update ONIE. ONIE 2026.08 refuses that command in Install OS mode.

An upstream ONIE update without embedding preserves the installed NOS. NVIDIA's ONIE upgrade for the Cumulus Linux Secure Boot case above factory-resets the switch. Replace the example hostname and path with the chosen updater's URL.

onie-self-update http://image-server/onie-updater

Enter ONIE after the update and compare onie-sysinfo -v with the updater version. An x86 update can refuse a BIOS-to-UEFI change or an incompatible disk layout. Treat that refusal as a reason to review the procedure, since embedding erases the disk.

The command onie-self-update -e embeds ONIE on x86 and reformats the disk. Use embedding only when the procedure requires recreating the disk layout. On the U-Boot designs, a normal update can rewrite U-Boot as well as ONIE in NOR flash.

On x86_64 systems using GRUB, ONIE 2026.08 provides onie-fwpkg add to stage firmware packages for the next ONIE update. When the pending-update directory exists, ONIE checks its queued packages before trying any discovered installer source. An image URL passed to onie-nos-install or onie-self-update takes precedence over the queue, as does the install_url kernel argument. Update and Embed modes accept only updater images, and Rescue accepts both updater and NOS images. During an Install OS boot, ONIE rejects a queued updater image, logs the failure and continues with NOS installer discovery. The rejected package remains queued for the next discovery pass, and the current pass skips the remaining queued packages.

Choose the Platform Before Replacing the NOS

For a new open networking deployment, choose the switch variant supplied with ONIE and a NOS release that supports the hardware and port layout you need. Resolve the image and Secure Boot requirements before the switch reaches the installation bench.

On a switch in service, use Rescue for a manual NOS installation. Select ONIE: Uninstall OS only when the replacement requires erasing the existing system. On x86, use ONIE: Embed ONIE only when the replacement requires erasing the disk and recreating its layout. Before starting a network installation, connect the console and check ONIE's management address and route to the server holding the correct installer. Postpone an erase or boot-environment change until the configuration backup and recovery preparations above are complete.

Hardware Nation is a partner of Arista and NVIDIA.

Alex Cronin

Alex Cronin is the founder of Hardware Nation and Nanites AI. He is a graduate of Georgia Tech with 20 years of experience in networking and data center infrastructure across enterprises, service providers and hyperscalers. His work spans traditional and open networking, production SONiC deployments, multivendor integration and direct collaboration with manufacturers and engineering teams. Hardware Nation has served organizations including NASA, Lockheed Martin, Accenture, Stanford University and Georgia Tech.

Alex leads engineering teams and contributes directly to architecture, code, integration and evaluation. At Nanites AI, he has led nearly two years of development of an agentic NetOps platform for network troubleshooting. He also develops AI automation for product research and leads business operations at Hardware Nation.

Nanites AI has been cited in Gartner’s Market Guide for Agentic NetOps Software, covered by InformationWeek and discussed by Cisco DevNet. It was selected as one of 12 finalists from more than 400 applicants in the 2025 T Challenge, organized by T-Mobile and Deutsche Telekom. Alex has presented his work at Deutsche Telekom in Bonn, CableLabs and Network X Americas.