ONIE Explained: Bare-Metal Switch Provisioning and Secure Boot

ONIE, the Open Network Install Environment, is a small Linux and BusyBox system that ships as firmware on bare-metal network switches. On first boot it finds a network operating system installer over USB, DHCP, HTTP or TFTP, runs it, then steps aside. It lets you choose your switch software, and it is also the most privileged code path on the box.

ONIE decides which installer runs on a new switch, stays on disk as the recovery and update path for the life of the hardware, and on x86 can boot through a UEFI Secure Boot chain. This guide covers each part from the ONIE design specification and source, then shows how to stage and verify an install and where the trust gaps are.

For switch ASICs and how a network operating system drives them, read how a network switch is made; this post does not repeat it.

Key takeaways

• ONIE is a boot loader plus a small Linux kernel and BusyBox environment that runs on the switch's management CPU, not on the forwarding ASIC. Its job is to locate and run a network operating system (NOS) installer.
• Discovery follows a fixed order in the design specification: a static URL from the boot loader, local file systems such as USB, exact URLs from DHCPv4, inexact URLs built from DHCP responses, IPv6 neighbours and a TFTP waterfall. ONIE loops through them forever, sleeping 20 seconds between rounds, until an install succeeds.
• ONIE identifies itself in DHCP with option 60 (onie_vendor: plus the platform string), option 77 (onie_dhcp_user_class) and option 125 under IANA enterprise number 42623, which IANA lists for the Open Compute Project.
• Later boots skip ONIE; the NOS can send the switch back in install, rescue, uninstall, update, embed or diag mode.
• ONIE secure boot uses the Linux shim method on x86 UEFI: firmware verifies shim, shim verifies GRUB with an embedded vendor certificate, and GRUB verifies the kernel through shim. Support arrived in release 2018.05, and release 2021.11 added a secure boot build and demonstration tutorial.
• Secure Boot protects ONIE's own boot chain. In the upstream installer runner we read, a downloaded NOS installer is checked for image type and then executed, so image integrity in transit and at rest is something your process has to add.
• A NOS image is a full Linux distribution. Keep an SBOM per image and record its kernel and userspace versions.

What is ONIE and where did it come from?

The ONIE documentation describes it as "a small operating system, pre-installed as firmware on bare metal network switches, that provides an environment for automated provisioning." The overview is more specific: it combines a boot loader with a modern Linux kernel and BusyBox, runs on the switch's management subsystem, and exists to install whichever network operating system the owner chooses.

The project sits under the Open Compute Project (OCP), with source at github.com/opencomputeproject/onie. The documentation carries a "2013-2018, Cumulus Networks, Inc." copyright, which points to where the code started, and GitHub's API shows the opencomputeproject/onie repository was created on 25 June 2014. The OCP networking project page refused our scripted client, so we could not confirm from OCP the year ONIE was contributed.

The FAQ says ONIE is released every three months. The news page lists releases through 2026.08, released on 19 August 2026, preceded by 2025.11 on 18 November 2025 and 2025.08 on 20 August 2025; many older entries announce new hardware platforms.

What problem does ONIE solve for white box and bare metal switches?

The overview states the problem plainly: "Before the advent of ONIE, Ethernet switches were procured with pre-installed, captive operating systems." The hardware and software came as one appliance from one supply chain. If you wanted a different operating system, you bought different hardware.

ONIE separates those two purchases. A hardware maker ships a switch with ONIE installed, and the buyer or a reseller installs the NOS during data centre provisioning, "in the fashion that servers are provisioned," as the overview puts it. Suppliers can stock a small number of hardware SKUs because one box runs several operating systems, and operators can automate switch provisioning with the DHCP, HTTP and inventory systems they already run for servers. "White box" and "bare metal" both describe this model: switch hardware sold without a bundled NOS. The zero touch provisioning guide covers what happens after the NOS boots and pulls its configuration; ONIE is the step before that.

Where does ONIE run on the switch?

A modern switch has two halves. The forwarding plane is the switch ASIC and its front panel ports. The management subsystem is a small computer with its own CPU, mass storage (the spec mentions mSATA cards and USB NAND flash), a serial console and an out of band Ethernet port. The overview stresses that this subsystem "can function independently from the switching ASIC(s)." ONIE uses only the management side. Installer traffic goes through the management Ethernet port, not a front panel port.

The discovery chapter lists three CPU architectures, arm, powerpc and x86_64. Each machine gets a platform string of the form <ARCH>-<VENDOR>_<MODEL>-r<REVISION>, for example x86_64-VENDOR_MACHINE-r0. It appears in default file names, the DHCP vendor class and HTTP headers, alongside a switch silicon vendor string that lets an installer match the forwarding chip.

How does ONIE boot?

On the first boot of a new machine, the boot loader starts ONIE, ONIE brings up the management port, runs discovery, downloads an installer and executes it. The installer writes the NOS to disk and changes the boot configuration so the NOS boots next.

On subsequent boots, the system goes straight into the NOS and ONIE does not run. The overview is explicit: "ONIE is not used on every boot of the system." ONIE stays on the disk in its own partition so the NOS can hand control back for reinstall, rescue, uninstall or update.

The x86 UEFI layout

ONIE added UEFI support in release 2015.08, according to the x86 UEFI chapter. Before that, x86 ONIE supported only legacy BIOS or UEFI in compatibility (CSM) mode, which the spec calls "non-trivial and prone to implementation errors" when switching between NOS and ONIE. The UEFI design targets UEFI specification 2.4 errata B or later and requires a GPT partition table.

On first install, the ONIE installer:

1. Creates an empty GPT partition table on the disk.
2. Creates the EFI System Partition (ESP) with the standard GPT type GUID C12A7328-F81F-11D2-BA4B-00A0C93EC93B and a FAT32 file system, and mounts it at /boot/efi.
3. Creates an ONIE-BOOT partition with GPT type GUID 7412F7D5-A156-4B13-81DC-867174929325 and mounts it at /mnt/onie-boot.
4. Installs the ONIE kernel and initramfs into ONIE-BOOT.
5. Installs UEFI GRUB at /boot/efi/EFI/onie/grubx64.efi, with GRUB modules and configuration in /mnt/onie-boot/grub.
6. Creates a UEFI Boot#### entry for that GRUB binary and puts it first in BootOrder.

The spec says ONIE is installed in the factory "via the network using PXE or via a directly attached USB flash drive," and that this step erases all previous partitions and data. After that, the ONIE GRUB menu offers Install OS, Rescue, Uninstall OS, Update ONIE and Embed ONIE.

ONIE's kernel enables CONFIG_EFIVAR_FS so UEFI variables appear under /sys/firmware/efi/efivars, and it ships efibootmgr, which installers use to change boot order.

U-Boot platforms have their own design chapter, with the same principle: ONIE stays resident and the NOS asks it to run in a given mode.

How does ONIE discover an installer?

The design specification is precise about the order. The first method that finds an installer is used. If that installer fails, ONIE moves on to the next method.

The overview page also lists mDNS and DNS-SD among the methods ONIE "uses ... including, but not limited to," but the ordered list in the discovery chapter does not include them. Treat that as a documentation gap and test on your platform before relying on it.

The spec's pseudo code makes the loop explicit: configure the management port, try method 1 through method N, sleep for 20 seconds, repeat. In its words, "The discovery methods are tried repeatedly, forever, until a successful image install occurs." That is a useful property on a factory floor and a risky one on a shared network, which we come back to under common mistakes.

Default file names

Several methods search for a list of default installer names, from most specific to least. For a hypothetical x86_64 machine the spec gives this order:

onie-installer-x86_64-VENDOR_MACHINE-r0
onie-installer-x86_64-VENDOR_MACHINE-r0.bin
onie-installer-x86_64-VENDOR_MACHINE
onie-installer-x86_64-VENDOR_MACHINE.bin
onie-installer-VENDOR_MACHINE
onie-installer-VENDOR_MACHINE.bin
onie-installer-x86_64-SWITCH_SILICON_VENDOR
onie-installer-x86_64-SWITCH_SILICON_VENDOR.bin
onie-installer-x86_64
onie-installer-x86_64.bin
onie-installer
onie-installer.bin

Two version notes from the spec matter for mixed fleets. ONIE 2016.05 introduced the CPU architecture plus switch silicon vendor name, and ONIE 2017.08 added the .bin variants. An older ONIE will not look for either. In update mode the prefix changes from onie-installer to onie-updater.

Bringing up the management port

Before any network method can run, ONIE configures the management port in this order: a static ip kernel command line argument, DHCPv6 (which the spec marks "Planned, but not yet implemented"), DHCPv4, then an IPv4 link local address per RFC 3927. In practice that means DHCPv4 for most installs, or link local addressing when you plug a laptop straight in.

What ONIE sends in DHCP

ONIE tells the DHCP server what it is so the server can choose the right answer. The request carries four options:

Inside option 125, ONIE defines five sub-options with one byte codes and one byte lengths:

RFC 3925 defines VIVSO as a way to carry several vendors' option sets inside one DHCP option, each keyed by a 32 bit IANA Private Enterprise Number. The IANA enterprise numbers registry lists 42623 as "Open Compute Project", which matches the spec. Option 114, the default URL, comes from RFC 3679, which documented it among DHCP option codes that were then unused or in limited use.

What ONIE sends in HTTP

Every HTTP request ONIE makes carries a set of headers that an HTTP application can use to pick an image or log the install:

A provisioning server can use these to tie a serial number to the image it served. The spec lists ONIE-SECURITY-KEY but does not say how the value is generated or what a server should do with it, so do not treat it as authentication.

Exact URLs, partial URLs and the waterfall

When DHCP gives an exact URL, ONIE fetches it. The spec lists four ways to form one: VIVSO sub-option 1, option 114, option 150 plus option 67, or option 66 plus option 67 (the last needs DNS).

When it does not, ONIE tries every default file name over HTTP on each server DHCP mentioned: option 72 (HTTP server IP), option 150 (TFTP server IP) and option 54 (the DHCP server itself). If DNS resolves a host called onie-server, ONIE tries it too, over HTTP and TFTP. The spec's reason: the team that runs DHCP is often not the team installing switches.

The TFTP waterfall is the last resort and the most PXE like. A worked example from the spec, for a switch whose management MAC is 55:66:AA:BB:CC:DD and whose DHCP address is 192.168.1.178:

1. Convert the MAC to lower case hex with dashes: 55-66-aa-bb-cc-dd/.
2. Convert the IP to upper case hex: 192 is C0, 168 is A8, 1 is 01, 178 is B2, giving C0A801B2/.
3. Drop one hex digit at a time: C0A801B/, C0A801/, C0A80/, C0A8/, C0A/, C0/, C/.
4. Finally try the default file names at the server root.

One TFTP tree can therefore hold per switch, per subnet and fleet wide images. A second worked example: a switch at 10.20.30.40 becomes 0A141E28, so a directory named 0A14 on the TFTP server would match every management address from 10.20.0.0 to 10.20.255.255, while 0A141E would match only 10.20.30.0 to 10.20.30.255. The upstream exec_installer script builds exactly this list with printf %02X%02X%02X%02X and a loop that trims the string from eight characters down to one.

The overview prefers HTTP for image download because it performs better with large images, and says TFTP is supported but "its use is discouraged in favor of HTTP." Our TFTP explainer covers why TFTP is slow and has no authentication.

Neighbour discovery for a crash cart install

The neighbour method exists for one scenario: someone wheels a laptop up to a rack, plugs it into the management port and runs a web server. ONIE pings the IPv4 broadcast address and the IPv6 all nodes address, then requests each default file name from every host that answered. The upstream script first probes port 80 on each candidate with nc, then tries the names. The user guide says its easy methods suit "a small number of switches as a proof of concept or for a demo."

Read that again from the other side. Any host on the management segment that answers a ping and serves a file named onie-installer is a candidate installer source for any switch sitting in ONIE install mode on that segment.

What the installer receives

Before it runs the installer, ONIE marks it executable and exports environment variables. The core set is onie_exec_url, onie_platform, onie_vendor_id, onie_serial_num and onie_eth_addr. Every DHCP response option is exported too, in BusyBox udhcpc style, such as onie_disco_ip and onie_disco_hostname, so the installer can name the switch or register it with inventory.

What network operating systems install through ONIE?

ONIE does not care what the installer installs, as long as it follows the interface. The design spec and documentation show four broad categories.

1. Open community NOS distributions. SONiC (Software for Open Networking in the Cloud) is the best known; the SONiC Foundation describes itself as a Linux Foundation project, and the SONiC Quick Start installs an "ONIE image" with the commands described here.
2. Commercial Linux based network operating systems sold separately from the hardware. They ship ONIE compatible installers and use the same discovery path.
3. General purpose Linux distributions. The x86 UEFI chapter uses a CentOS install as its worked example.
4. Hardware diagnostics operating systems (HDOS). The hardware maker's diagnostic image installs like a NOS but into a partition named <SOMETHING>-DIAG with the GPT system partition attribute bit set. Neither ONIE uninstall nor a compliant NOS may touch it.

The SONiC Quick Start shows the manual path: set a management address and gateway at the ONIE prompt, run onie-nos-install with the image's HTTP URL, and "When NOS installation finishes, the box will reboot into SONiC by default." It also notes that some hardware uses its own boot loader and image format instead of ONIE.

How the NOS takes over

The spec asks little of the NOS installer: make the NOS boot on the next reboot, and on success call onie-nos-mode -s. Beyond that it may fetch files, talk to inventory systems or kexec into a new kernel.

On x86 UEFI, a typical installer:

1. Creates its own partitions and file systems in the free space after ONIE-BOOT.
2. Installs the NOS kernel, initramfs and root file system.
3. Installs its UEFI boot loader at /boot/efi/EFI/<NOS>/<loader>.
4. Creates a new Boot#### entry and puts it first in BootOrder.
5. For GRUB based systems, adds a GRUB entry that chainloads ONIE. ONIE ships a helper, 50_onie_grub, to drop into /etc/grub.d so update-grub keeps the entry.

What ONIE modes exist?

The NOS interface chapter defines the operations ONIE provides after a NOS is installed, and the x86 chapter lists the onie-boot-mode values that select them.

On x86 the NOS and ONIE communicate through GRUB environment variables stored on the ONIE-BOOT partition. The NOS mounts that partition by label and calls the onie-boot-mode tool there, which is a thin wrapper around grub-editenv that sets onie_mode. Then it uses grub-reboot ONIE so the NOS's GRUB boots the ONIE chainload entry once. The spec's commands for a reinstall are:

# From a running Linux based NOS (x86). This reboots into ONIE install mode.
mkdir -p /mnt/onie-boot
mount LABEL=ONIE-BOOT /mnt/onie-boot
grub-reboot ONIE
/mnt/onie-boot/onie/tools/bin/onie-boot-mode -o install
reboot

On UEFI the one time return can also use the BootNext variable, which boots a given entry once and then falls back to BootOrder.

Rescue mode deserves a careful read. The spec says that in rescue mode "you can connect to ONIE via the serial console or via telnet," and the user guide says "ONIE does not require a password for either ssh or telnet." Rescue mode is discovery switched off, with tools such as onie-nos-install, onie-self-update, onie-sysinfo and onie-support (a tarball of logs for a support case).

How are ONIE and switch firmware updated?

Updating ONIE itself

The updater chapter describes ONIE self update as discovery with a different image type. The default names use onie-updater- instead of onie-installer-, and VIVSO uses sub-option 2 instead of 1. From rescue mode you can run onie-self-update <URL>.

An ONIE update image is a self extracting shell archive that must contain the string ONIE-UPDATER-COOKIE. It supports -x (extract), -i (dump image information) and -f (force, "bypassing any safety checks"). The upstream exec_installer script checks the image type against the boot reason: in install mode it refuses an updater, in update or embed mode it refuses a NOS installer, and in rescue mode it allows either.

onie-self-update -e embeds instead, which the CLI reference warns "is destructive to the data on the hard disk."

Updating BIOS, UEFI and CPLDs through ONIE

The firmware update chapter defines firmware as three things: the ONIE software itself, the BIOS or UEFI firmware ("The data that lives in an 8MB SPI-ROM on most x86 platforms") and CPLD programs ("3 seems typical"), usually loaded over JTAG signals driven from a GPIO controller on the CPU complex.

Firmware updates run in ONIE context, not in the NOS, because hardware vendors own both ONIE and the firmware and ONIE is NOS agnostic. Operators get one update path per switch model whatever NOS runs on it.

Firmware updates use the same discovery as ONIE updates, and for x86_64 fleets already running a NOS the spec adds staging:

1. From the NOS, download the vendor's firmware update image.
2. Stage it in the ONIE update directory on the ONIE-BOOT partition with onie-fwpkg.
3. Reboot into ONIE update mode.
4. ONIE processes every staged image in lexicographical order and writes a results record for each, stored on the ONIE partition.
5. The switch reboots back into the NOS.

If a CPLD change needs a cold boot, the update can drop an executable at /tmp/reboot-cmd and ONIE will use it. In the upstream x86 helper, max_fw_attempts is set to 5, after which ONIE stops retrying a failing staged update. PowerPC and ARM platforms have no staging partition and use the network or onie-self-update instead.

What does ONIE secure boot add?

The old OCP hosted slide deck on ONIE secure boot that the project's news page links to now returns HTTP 404, so this section is built from the x86 UEFI design chapter, the README.secureboot file in the repository's kvm_x86_64 machine and the build scripts.

The chain of trust

The design spec says "The ONIE build system supports the Linux shim method of x86 UEFI Secure Boot." The chain has three signed links:

The README spells out the shim step: shim "will first attempt to verify the signature on grubx64.efi by using the UEFI db signature database. If that fails, shim goes on to check the signature against the compiled in public certificate." The shim README adds that shim refuses forbidden binaries or keys and, with a TPM, extends PCRs with digests of what it loads.

The model has three actors: a trusted hardware supplier, a trusted OS software supplier and a trusted ONIE software supplier. The hardware supplier owns the platform key (PK), plus a KEK and a db key for its own signed tools. The OS software supplier has a KEK and a db key and signs shims for vetted third parties. The ONIE software supplier has one key pair: the public half is compiled into shim, the private half signs GRUB and the kernel. In the README's words the PK "is the master key of the entire system," the KEK controls updates to db, and dbx holds revoked keys.

Building a secure boot ONIE

The spec lists the prerequisites as a 2048 bit RSA key pair in PEM format, the matching x509 certificate and a shimx64.efi signed by Microsoft. Building is "a four step process":

1. Compile shim with the hardware vendor's certificate embedded (SECURE_BOOT_ENABLE=yes and ONIE_VENDOR_CERT_DER).
2. Submit the shim to Microsoft for code signing.
3. Submit the shim source for open source community review, which Microsoft requires.
4. Build the ONIE installer with the signed shim (SHIM_PREBUILT_DIR) and the vendor key that signs GRUB and the kernel (ONIE_VENDOR_SECRET_KEY_PEM, ONIE_VENDOR_CERT_PEM).

The README says getting shim signed "takes on the order of weeks" and one signed shim serves every platform from the same hardware supplier. On the private key it is blunt: "This key is very sensitive and should be protected. In practice, this key should never be checked into the ONIE code repository."

The kvm_x86_64 machine in the repository includes a full set of example keys in its x509 directory, private keys included, for testing in a virtual machine, and the README warns in capitals not to follow those steps for production. Those keys are public, so anything they sign proves nothing.

Newer releases added an encryption/ directory whose onie-encrypt.sh can generate demonstration keys and "Run a signing audit to confirm what has been signed and how." signing-keys.make lists separate shim, GRUB, kernel and image keys, a GPG keyring and a GRUB password hash, and a 2021 gpg-sign.sh script creates detached GPG signatures. For checking state, the README shows mokutil --sb, which prints "SecureBoot enabled" when it works, and mokutil --pk, --kek and --db to dump certificates.

Revocation and SBAT

Secure Boot is only as good as its revocation. The shim project's SBAT document explains why certificate revocation is impractical for the broad UEFI signing authorities and why the dbx space is small: after the 2020 "BootHole" GRUB issue, CVE-2020-10713, three certificates and 150 image hashes were added to dbx on x64, consuming "10kB of the 32kB, or roughly one third" of revocation storage typically available. SBAT (Secure Boot Advanced Targeting) adds generation numbers so a class of vulnerable builds can be revoked without listing every hash. When a shim or GRUB revocation is enforced, old ONIE builds stop booting until you update ONIE.

What secure boot does not cover

Secure boot verifies that the firmware, shim, GRUB and kernel that start ONIE are the ones the supplier signed. It does not, by itself, verify the NOS installer that ONIE downloads.

In the upstream rootconf/default/bin/exec_installer on the master branch as we read it on 25 October 2026, run_installer checks the image type against the current mode, runs chmod +x and executes the file. We did not find a signature or hash check in that path. The URL handler accepts http, https, ftp, tftp and file schemes, and the user guide's examples all use plain HTTP. Vendor builds may add installer verification (the build system has image key and GPG variables), so confirm what your ONIE build verifies with your hardware vendor. Until you have, assume that whoever can serve a file to a switch in ONIE install mode can run code on it as root.

After install, the NOS's own boot chain, and whether its loader is signed, is the NOS's job. Read the Unified Kernel Images explainer for how a Linux system can sign kernel, initramfs and command line as one unit, and the TianoCore EDK II explainer for the firmware underneath.

Timeline: the ONIE features this post relies on

ONIE install versus vendor pre-installed NOS versus PXE install

Our PXE and UEFI HTTP boot explainer covers the third column. ONIE behaves like a PXE client that lives on disk and never stops trying, so the same network hygiene applies.

Step by step: stage a NOS image, set DHCP, install and verify

This walkthrough uses a Linux image server, ISC DHCP syntax from the ONIE user guide and an x86 switch. Names and addresses are examples; use the file names and vendor class string your suppliers give you.

Warning: installing a NOS through ONIE repartitions the switch's internal disk. ONIE uninstall wipes everything except ONIE, and ONIE embed wipes everything including the NOS. Run these steps only on a switch you intend to reimage, on an isolated provisioning network, and confirm the target with onie-sysinfo first.

Step 1: put the provisioning network on its own segment

Give the management ports of switches waiting for install a dedicated VLAN or physical network that contains only your DHCP server, your image server and the switches. Discovery will try broadcast neighbours, the DHCP server's own address and any host named onie-server, so every host on that segment is part of your trust boundary.

Step 2: stage the image and record its digest

# On the image server
sudo mkdir -p /srv/onie/images
sudo cp nos-image.bin /srv/onie/images/
cd /srv/onie/images

# Record the digest you will compare against later.
sha256sum nos-image.bin | sudo tee nos-image.bin.sha256

# Compare with the digest the image publisher gives you.
cat nos-image.bin.sha256

If your NOS supplier publishes a signature or checksum, verify it here, and store the expected digest somewhere the image server cannot change.

Step 3: serve it over HTTP from the provisioning network only

# Minimal example using the Python standard library, bound to the provisioning interface address.
cd /srv/onie/images
python3 -m http.server 8080 --bind 192.0.2.10

Any web server works; bind it to the provisioning address only. Test the URL from another host with curl -sI http://192.0.2.10:8080/nos-image.bin before you power on a switch.

Step 4: set DHCP options for ONIE clients only

The user guide shows how to match ONIE requests on the vendor class identifier and return an exact URL with option 114 (default-url). This version answers only ONIE clients of one platform:

# /etc/dhcp/dhcpd.conf (ISC DHCP syntax as shown in the ONIE user guide)
subnet 192.0.2.0 netmask 255.255.255.0 {
  range 192.0.2.100 192.0.2.199;
  option routers 192.0.2.1;
  option domain-name-servers 192.0.2.2;
}

class "onie-x86-vendor-machine" {
  match if substring(option vendor-class-identifier, 0, 36) = "onie_vendor:x86_64-VENDOR_MACHINE-r0";
  option default-url = "http://192.0.2.10:8080/nos-image.bin";
}

Set the substring length to the exact length of your vendor class string (36 characters in this example). The user guide suggests temporary log() lines to see what the switch actually sends. If you prefer VIVSO, the guide gives the ISC option space definitions for enterprise 42623 and sub-option 1, the installer URL; it is more precise but takes more configuration.

Step 5: boot the switch into ONIE install mode

On a new switch, power on: ONIE starts in install mode. On a switch already running a NOS, use the NOS interface shown earlier (grub-reboot ONIE plus onie-boot-mode -o install on x86), or pick "ONIE: Install OS" from the GRUB menu on the serial console. Watch the console. ONIE logs each URL it tries and prints "Executing installer:" with the URL it chose.

Step 6 (manual alternative): verify the hash inside ONIE before running it

When you want a human check before install, boot into rescue mode instead, so discovery does not run on its own:

# On the switch console, in ONIE rescue mode.
onie-sysinfo -p        # platform string: confirm this is the switch you mean
onie-sysinfo -s        # serial number
onie-sysinfo -v        # ONIE version

# Fetch the image to RAM and check it against the digest you recorded in step 2.
cd /tmp
wget http://192.0.2.10:8080/nos-image.bin
sha256sum nos-image.bin
# Compare the printed digest with your recorded value by eye or with a script.

# Only if it matches: install from the local file.
onie-nos-install /tmp/nos-image.bin

The ONIE CLI reference lists local files among the URL types onie-nos-install accepts. Whether sha256sum is present depends on how your ONIE was built, so check; if it is missing, verify on a trusted host instead.

Step 7: confirm the installed version

After the install, the switch reboots into the NOS. Confirm what you meant to install is what is running:

# In the NOS. For SONiC, the CLI shows the software version and build details.
show version
uname -r
cat /etc/os-release

Record the NOS version, the kernel version and the image digest against the switch serial number. The onie_serial_num and onie_eth_addr values ONIE exported to the installer, and the ONIE-SERIAL-NUMBER header your web server logged, give you the join key.

Step 8: record ONIE's own version

Run onie-sysinfo -v in rescue mode on a sample switch per model and revision, and keep a table of ONIE versions across the fleet, because discovery behaviour differs between ONIE releases.

The supply chain angle: a NOS image is a Linux distribution

A NOS installer is not one program. It is a kernel, a root file system, a distribution's worth of userspace, often containers, and the drivers that talk to the switch ASIC. SONiC is a good example: its wiki tracks the Debian versions used for each branch and documents services such as syncd running in Docker containers, yet the Quick Start installs it from a single .bin file. When a vulnerability lands in OpenSSL, the kernel, a routing daemon or a container runtime, you need to know which images, and so which switches, carry the affected version.

Practical steps:

• Keep an SBOM per image. Generate or obtain a CycloneDX or SPDX SBOM for every NOS image you deploy, keyed by the image digest you recorded in step 2. If you build your own NOS from source, generate it in the build. If you receive a binary image, ask the supplier for one.
• Track the kernel and userspace separately. Kernel fixes and userspace fixes arrive on different schedules. Record uname -r and the base distribution version for each image.
• Map images to switches. Join the image digest to the serial numbers that installed it, using the ONIE headers or environment variables.
• Treat ONIE as a component too. ONIE itself is built from upstream projects: a Linux kernel, BusyBox, GRUB, shim, Dropbear (the news page notes Dropbear was upgraded in 2022.02), pesign, mokutil and more. The build pins upstream tarballs with checksum files in its upstream/ directory, for example pesign-113.tar.bz2.sha1. Ask your hardware vendor for the ONIE version and component list on each model.

The same reasoning applies to the server side of a neocloud rack: BMC firmware, boot loaders and provisioning images are software with dependencies, even when they arrive pre-installed.

Common mistakes

• Serving installers over plain HTTP on a shared network. ONIE's discovery tries neighbours, the DHCP server's own address and any host named onie-server. On a segment shared with other systems, any host that answers can become an installer source. Use a dedicated provisioning network, return exact URLs from DHCP, and use HTTPS if your ONIE build and NOS supplier support it.
• No image verification. Upstream ONIE runs the installer it downloads after an image type check. Record the expected digest, verify it on the image server, and use the rescue mode check in step 6 when you need a human gate.
• Leaving ONIE rescue reachable. The user guide says ONIE does not require a password for SSH or telnet. Do not leave switches sitting in rescue or install mode on a routed network, and restrict which hosts can reach management ports.
• Treating the demo secure boot keys as real. The kvm_x86_64 example keys in the repository are public, private halves included. A build signed with them proves nothing.
• Assuming Secure Boot is on. Check with mokutil --sb in ONIE and with your NOS's tools after install. A platform can ship with Secure Boot available but disabled.
• Mixing ONIE versions across a fleet. Default file names changed in 2016.05 and 2017.08, UEFI arrived in 2015.08 and secure boot in 2018.05. A file name that works on one switch may never be requested by another. Keep an inventory of ONIE version by model and revision.
• Using embed when you meant update. onie-self-update -e and the embed mode wipe the disk, including the NOS. Update mode only touches ONIE-BOOT.
• Forgetting the TFTP waterfall. A stray short directory such as 0A/ at the TFTP root matches a wide range of addresses.
• No record of what was installed where. Without the image digest, NOS version and serial number joined together, you cannot answer "which switches run the vulnerable image" quickly.

FAQ

What does ONIE stand for?

Open Network Install Environment, an Open Compute Project networking project.

Is ONIE a network operating system?

No. It is a small Linux and BusyBox environment that installs a NOS. It runs on first boot and when the NOS asks for it, not on every boot.

What DHCP option does ONIE use for the installer URL?

ONIE accepts an exact URL from option 114 (default URL), from VIVSO option 125 sub-option 1 under enterprise number 42623, or from a TFTP server address or name (option 150 or 66) plus a bootfile (option 67). It also sends option 60 as onie_vendor: plus its platform string, which you can match on.

Does ONIE support HTTPS?

The upstream exec_installer passes https URLs to wget like http ones. Whether certificates are checked depends on your ONIE build, so test it; the user guide's examples use plain HTTP.

Does ONIE secure boot verify the NOS installer?

It verifies ONIE's own chain: shim, GRUB and the kernel. Upstream, the downloaded installer gets an image type check, not a signature check; ask your hardware vendor whether their build adds one.

How do I get back into ONIE from SONiC or another NOS?

On x86, mount the ONIE-BOOT partition, run grub-reboot ONIE, then run onie-boot-mode -o install (or rescue, uninstall, update) from /mnt/onie-boot/onie/tools/bin/, and reboot. You can also choose ONIE from the GRUB menu on the serial console.

What is the difference between ONIE update and ONIE embed?

Update replaces ONIE on the ONIE-BOOT partition and keeps the NOS. Embed wipes the disk and reinstalls ONIE, removing the NOS. The spec says embed is typically done in manufacturing and is available on x86 only.

How do I update switch BIOS or CPLD firmware with ONIE?

Use the hardware vendor's ONIE firmware update image. On x86_64 you can stage it from the running NOS with onie-fwpkg, reboot into ONIE update mode and let ONIE apply it, then return to the NOS. Other architectures use network discovery or onie-self-update.

Where Safeguard fits

Safeguard's fit here is indirect. It does not run on switches, install or verify NOS images, manage devices, scan firmware images, generate hardware bills of materials or run ONIE. Those jobs belong to your provisioning system, hardware vendor and NOS supplier.

Where Safeguard helps is the software you build and the SBOMs you hold around the fleet. If you build your own NOS image, the image build repository, its container images and the SBOM it produces can be scanned with the Safeguard CLI (safeguard scan --dir ., --image <name>, --sbom <file>), with results written as JSON under ./output. If your NOS supplier gives you an SBOM per image, you can import it, and Safeguard shows which projects contain a given component and version and matches components against vulnerability databases. Policies and gates evaluate those results; gate actions are Block, Warn and Notify, and teams approve exceptions through the platform rather than switching a gate off. The DHCP and HTTP automation and inventory services that drive ONIE are ordinary repositories too. Coverage depends on what you feed it: Safeguard can only tell you about an image whose SBOM it has.

A switch fleet reimaged through ONIE pulls a full Linux distribution onto every box, and the NOS images, provisioning tools and container workloads around them ship open source components that need the same patch discipline as any service. The fit is indirect for ONIE itself and for vendor firmware, but direct for the images and tooling you build and the SBOMs you keep for them.

Fix it without waiting for upstream

Whatever the vulnerability, most of the risk sits in two gaps. The first is the time between a fix being published and that fix actually running in your production builds. The second, and worse, is the time before any fix exists at all, while a maintainer works out a patch and a release schedule. Waiting through both gaps is a habit, not a requirement. Safeguard gives teams three ways to close them.

1. Autonomous remediation: pull requests, not tickets

When a fixed version exists, Safeguard's Griffin models open a tested, policy gated pull request that moves the affected dependency to the safe version. You can run it on one repository or in bulk across every project that carries the vulnerable version. Remediation categories include dependencies, licenses, security posture and findings, and each one is set separately. Reachability analysis ranks the vulnerable code paths your application actually calls first, so the first pull requests you merge are the ones that matter most. Autonomous remediation ships switched off, with every category set to Manual, so your team decides how much runs on its own and what still needs a human approval.

2. Gold Open Source: the safe version in seconds, free

gold.safeguard.sh is free and needs no login. Search any CVE or package to see affected and fixed versions, CVSS, EPSS, CISA KEV status and a recommended safe version, or use the "Am I affected?" checker. The same data is available through a free read API, README status badges and RSS threat feeds.

3. Gold Registry: start from components that are already fixed

Gold Registry provides hardened, drop in replacements for upstream packages and container images. Every Gold artifact is held continuously to zero exploitable critical or high CVEs and a completed license check, with signed build provenance (signed with Safeguard's key and verifiable with cosign, SLSA Build Level 3 as the design target) and a public evidence page you can hand to an auditor. An artifact loses its Gold badge if it regresses. Teams can point their own package directory at the registry so hardened equivalents resolve without changing how developers install anything.

When upstream has no fix yet, or will not ship one, Safeguard first works to get the fix accepted upstream. If the issue is severe or upstream will not move, Safeguard builds a fork, fixes the vulnerability there and publishes a hardened Gold build, so you are not stuck on a maintainer's release schedule. You can also request a hardened, compatibility tested build of a specific package. Ask which packages it covers before you plan around it.

One honest limit: when the vulnerable code lives in a vendor appliance, a hosted service or an operating system runtime you do not build yourself, the fix still has to come from that vendor or distribution. The steps above apply to the open source dependencies and container images you build and ship, which is where most teams carry the largest and least tracked share of their exposure.

See how Safeguard would help

These demos show Safeguard on ordinary software projects, not on switches. They fit the repositories that build NOS images and the provisioning tooling that serves them to ONIE.

The first demo is a real Safeguard CLI session. After install, safeguard opens the interactive terminal, you ask it to fix the lodash CVE in a repository, and it reads the finding and advisory, asks before any command that changes something, edits package.json to lodash 4.17.21, runs npm install and npm test with your approval, prints a summary and pushes nothing. It ends with /permissions, /model and /scan. The same loop suits a provisioning or inventory service whose dependency changes a person should review.

Click through it at your own pace, or open it full screen.

The second demo sets up the Safeguard local runner on your own machine, approves it with its device code and then runs a scan from the terminal. That suits a NOS build host whose repositories you want scanned where they live.

Click through it at your own pace, or open it full screen.

The third demo connects Claude to the Safeguard MCP server with OAuth and shows how you choose which tools Claude can use. A network engineering team can then ask about findings in the repositories and SBOMs behind their switch images, with Claude limited to the tools you allowed.

Click through it at your own pace, or open it full screen.

Safeguard's desktop and CLI downloads are at safeguard.sh/download, and the CLI documentation is at docs.safeguard.sh/docs/cli.

Quick check

Sources

• ONIE documentation home and news
• ONIE overview
• ONIE design specification index
• ONIE design spec: Image Discovery and Execution
• ONIE design spec: Network Operating System Interface
• ONIE design spec: x86 Interface Details
• ONIE design spec: x86 UEFI Firmware Support and Secure Boot
• ONIE design spec: Updating ONIE
• ONIE design spec: Firmware Updates
• ONIE User Guide
• ONIE Command Line Reference
• ONIE FAQ
• ONIE news
• ONIE source repository
• ONIE kvm_x86_64 README.secureboot
• ONIE exec_installer script
• ONIE onie-nos-install script
• ONIE x86 exec-installer-arch helper
• ONIE encryption directory README
• ONIE signing-keys.make
• ONIE gpg-sign.sh
• shim README
• shim SBAT document
• RFC 3925: Vendor-Identifying Vendor Options for DHCPv4
• RFC 3679: Unused DHCP Option Codes
• IANA Private Enterprise Numbers registry
• SONiC wiki
• SONiC Quick Start
• SONiC Foundation

Last reviewed: 25 October 2026.