This knowledge base has moved to the documentation site. Please visit the knowledge base here for the most up to date content. This site is no longer maintained.

[RETIRED] Using ONIE to Install Cumulus Linux


IMPORTANT! This article has been retired. The content has been moved into the Cumulus Linux user guide.





I have a bare metal switch with ONIE and want to install Cumulus Linux on it. How do I do this?


ONIE (Open Network Install Environment) supports numerous methods for installing a network OS. This article contains several examples, which are just a small subset of features ONIE has.

Note: The examples are ordered from the most repeatable to the least repeatable methods. For instance, DHCP can scale to hundreds of switch installs with zero manual input, compared to something like USB installs. Installing via USB is fine for a server here or there but is not scalable.

DHCP/Web Server Method with DHCP Options

This could be as simple as setting up a DHCP/Web server on your laptop and connecting the eth0 management port of the switch to your laptop.

Once you connect the cable, the installation proceeds as follows:

  1. The bare metal switch boots up and asks for an address (DHCP request).
  2. The DHCP server acknowledges and responds with DHCP option 114 and the location of the installation image.
  3. ONIE downloads the Cumulus Linux binary, installs and reboots.
  4. Success! You are now running Cumulus Linux.


Note: The most common method is for you to send DHCP option 114 with the entire URL to the Web server (this could be the same system). However, there are many other ways to use DHCP even if you don't have full control over DHCP. See the ONIE user guide for help.

Here's an example DHCP configuration with an ISC DHCP server:

subnet netmask {
  option default-url = "";

Here's an example DHCP configuration with dnsmasq (static address assignment):


Don't have a Web server? There is a free Apache example you can utilize.

DHCP/Web Server Method without DHCP Options

If you have a laptop on same network and the switch can pull DHCP from the corporate network, but you cannot modify DHCP options (maybe it's controlled by another team), do the following:

  1. Place the Cumulus Linux binary in a directory on the Web server.
  2. Run the onie-nos-install command manually, since DHCP options can't be modified:
    ONIE:/ #onie-nos-install

Web Server with no DHCP

Use the following method if your laptop is on the same network as the switch eth0 interface but no DHCP server is available.

One thing to note is ONIE is in discovery mode, so if you are setting a static IPv4 address for the eth0 management port, you need to disable discovery mode or else ONIE may get confused.

  1. To disable discovery mode, run:
    onie# onie-discovery-stop 
    or, on older ONIE versions if that command isn't supported:
    onie# /etc/init.d/ stop 
  2. Assign a static address to eth0 via ONIE (using ip addr add):
    ONIE:/ #ip addr add dev eth0
  3. Place the Cumulus Linux installer image in a directory on your Web server.
  4. Run the onie-nos-install command manually since there are no DHCP options:
    ONIE:/ #onie-nos-install

Using FTP or TFTP without a Web Server

  1. Set up DHCP or static addressing for eth0, as in the examples above.
  2. If you are utilizing static addressing, disable ONIE discovery mode.
  3. Place the Cumulus Linux installer image into a TFTP or FTP directory.
  4. If you are not utilizing DHCP options, run one of the following commands (tftp for TFTP or ftp for FTP):
    ONIE# onie-nos-install ftp://local-ftp-server/cumulus-install-powerpc.bin
    ONIE# onie-nos-install tftp://local-tftp-server/cumulus-install-powerpc.bin

Local File Installation

  1. Set up DHCP or static addressing for eth0, as in the examples above.
  2. If you are utilizing static addressing, disable ONIE discovery mode.
  3. Use scp to copy the Cumulus Linux binary to the switch.
    Note: Windows users can use WinScp.
  4. Run the following command:
    ONIE# onie-nos-install /path/to/local/file/cumulus-install-powerpc.bin

USB Installation

  1. Rename the Cumulus Linux installer image (for example, CumulusLinux-2.2.0-amd64) to onie-installer.
    Note: You can also use any of the ONIE naming schemes mentioned here.
  2. Make sure the USB stick is formatted as VFAT (which is common on commercially available USB sticks) or ext2.
  3. Copy the file onie-installer to the USB stick.
  4. Insert the USB stick into front port, making sure ONIE discovery mode is enabled (it is by default).
    Note: Not all switches have USB ports.
  5. Auto installation will occur, and you can watch it on your console.

Problems with Installation

onie-nos-install command does not exist

Several commands have been deprecated however certain older ONIE versions seems to be floating around that don't have the newer command. Instead of utilizing onie-nos-install use the command install_url

ONIE:/ #install_url

ONIE is in diag mode, not allowing installation

Sometimes certain vendors will have a special mode. One we have noticed in the field is diag mode which stops correct installation.

  1. To figure out what mode the switch is running in perform the following
    ONIE#cat /proc/cmdline and look at the boot_reason variable
    Diag mode will look like the following:
  2. When in diag mode we need to switch to install or rescue mode which will allow installation.  The difference being that install mode is running the discovery process and rescue mode is the exact same except its not running the discovery process (when manually performing an scp of an image or running a command without using the onie-installer method).
  3. To get into recovery mode or installation mode do the following:
    1. For x86 switches use the onie-boot-mode command
      ONIE#onie-boot-mode -o rescue
    2. For Powerpc switches follow the directions here
  4. Now follow normal installation directions above


ONIE does not install image due to not accepting DHCP address

See this article

See Also


This support portal has moved

Cumulus Networks is now part of the NVIDIA Networking Business Unit! The NVIDIA Cumulus Global Support Services (GSS) team has merged its operations with the NVIDIA Mellanox support services team.

You can access NVIDIA Cumulus support content from the Mellanox support portal.

You open and update new cases on the Mellanox support portal. Any previous cases that have been closed have been migrated to the Mellanox support portal.

Cases that are still open on the Cumulus portal will continue to be managed on the Cumulus portal. Once these cases close, they will be moved to the Mellanox support portal.

Powered by Zendesk