Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

Installing and Recovering Software Using the Open Network Install Environment (ONIE)

ONIE, the open network install environment from Cumulus Networks, is a network OS installer that installs Junos OS and third party applications on a switch. Juniper Network switches come pre-installed with ONIE. When you turn on a switch, the ONIE discovery and execution (ODE) application locates the management Ethernet interface and the Junos OS software package, which can be found either locally on the switch or on the network using HTTP, FTP, or TFTP. After the switch discovers and downloads the Junos OS software package, the switch installs the Junos OS software, reboots, and then boots from Junos OS. Junos OS then becomes the default software image.

Note:

If you want to use the Junos OS CLI to install software, see Installing Software Packages on QFX Series Devices (Junos OS).

Upgrading involves these tasks:

Understanding the Open Network Install Environment

When you log into the switch with ONIE, you see the install boot menu:

  • Juniper Linux (This is a default menu option.)

  • Juniper Linux Debug

  • Juniper Linux Recovery

  • Go to ONIE Loader

    • ONIE: Install OS (This is a default menu option.)

    • ONIE: Rescue

    • ONIE: Uninstall OS

    • ONIE: Update ONIE

    • ONIE: Embed ONIE

You can use the following commands to install and uninstall Junos OS and start and stop the ONIE ODE application:

  • onie-nos-install

    Installs Junos OS from any URL, such as http://, ftp://, and file://.

  • onie-uninstaller

    Uninstalls Junos OS.

  • onie-discovery-start

    The discovery process starts automatically. However, if you stop the discovery process by issuing the onie-discovery-stop command, you can restart the discovery process by issuing the onie-discovery-start command.

  • onie-discovery-stop

    Stops the discovery process. To restart the discovery process, issue the onie-discovery-start command.

Downloading Software Files with a Browser

You download the software package from the Juniper Networks Downloads page at https://support.juniper.net.

Note:

To access the download site, you must have a service contract with Juniper Networks and an access account. If you need help obtaining an account, complete the registration form at the Juniper Networks website https://www.juniper.net/registration/Register.jsp.

To download a software package:

  1. Using a Web browser, navigate to the https://support.juniper.net.
  2. Either click View all products> and select the product you are downloading software for, or type the product name.
  3. Find the package you want and click the item in the Downloads column.

    A login screen appears.

  4. Enter your name and password and press Enter.
  5. Read the End User License Agreement, click the I agree radio button, and then click Proceed.
  6. Save the Junos OS software image file to your computer.

    The Junos OS software image file name is presented in the prefix-release-edition-signed.extension format. For example, the image name for Junos OS Release 15.1X53-D10 on QFX10000 series switch is jinstall-qfx-10-f-15.1X53-D10.7-domestic-signed.

    See Junos OS Installation Package Names for additional information on image file naming.

  7. Open or save the installation package either to the local system in the var/tmp directory or to a remote location. If you are copying the installation package to a remote system, make sure that you can access it using HTTP, TFTP, FTP, or SCP.

Connecting to the Console Port

We recommend that you connect to the console port while installing the installation package so you can respond to any required user input and detect any errors that might occur.

Backing Up the Current Configuration Files

Before you install the new installation package, we strongly recommend that you back up your current configuration files because the upgrade process removes all of the stored files on the switch.

To back up your current configuration files, enter the save command:

Executing this command saves a copy of your configuration files to a remote location such as an external USB device.

Uninstalling the Existing Version of Junos OS

The switch comes preinstalled with a version of Junos OS that is to be used with the Junos OS CLI. However, if you want to use ONIE to install Junos OS, you need to uninstall the existing Junos OS and reinstall the Junos OS image that has a .bin extension—for example, jnpr-qfx-5e-jdm-onie-updater-15.1-20150819_ups.4.bin file.

To uninstall your existing Junos OS version:

  1. Select Go to ONIE Loader from the GNU GRUB menu.
  2. Select ONIE: Uninstall OS from the GNU GRUB menu.

    The Junos OS is uninstalled, and the switch reboots.

    By default, the ONIE discovery and execution (ODE) application attempts to discover and fetch an image from a configured DCHP or webserver and the management IP address of the switch and the IP address of the default gateway. If you want to manually configure static addressing for the management IP address of the switch, issue onie-discovery-stop command at the ONIE prompt, and then manually configure the management IP address and IP address of the default gateway.

    For example:

    To restart the ONIE discovery and execution (ODE) application, issue the onie-discovery-start command.

    For example:

Installing a Junos OS Software Package That Resides on a Webserver or DHCP Server with DHCP Options Configured

To install a Junos OS software package residing on a webserver or DHCP server:

  1. Copy the software image with the filename onie-installer to the var/www/html directory of the webserver or DHCP server.
  2. Configure the DHCP option 114 in the DHCP server to redirect to the webserver to fetch the Junos OS software image.
  3. Uninstall the preinstalled Junos OS version.

    • Select Go to ONIE Loader from the GNU GRUB menu.

    • Select ONIE: Uninstall OS from the GNU GRUB menu.

    The Junos OS is uninstalled, and the switch reboots.

  4. Configure DHCP option 114 and other DHCP options as necessary.

    Here is a sample Windows Open DHCP server configuration with DHCP option 114 configured.

    Here is a sample boot initialization log, showing the options you just configured:

    The log shows that the installation process has fetched the Junos OS software image from the DHCP server and is installing the Junos OS software.

    The switch reboots and the GNU GRUB menu is displayed.

Installing Junos OS Software Using Secure Copy Protocol (SCP)

To install Junos OS software using SCP:

  1. Uninstall the preinstalled Junos OS version.

    • Select Go to ONIE Loader from the GNU GRUB menu.

    • Select ONIE: Uninstall OS from the GNU GRUB menu.

    The Junos OS is uninstalled, and the switch reboots.

    By default, the ONIE discovery and execution (ODE) application attempts to discover and fetch an image from a configured webserver. If you do not have DHCP configured, you will need to stop the ONIE discovery and execution (ODE) application and manually configure static addressing for the management IP address of the switch,

    For example:

  2. Use SCP to copy the Junos OS image from a server or other location to the /var/tmp directory on the switch.

    For example:

  3. Issue the onie-nos-install command in the /var/tmp directory to install Junos OS software.

    The switch reboots and displays the GNU GRUB menu.

Installing Junos OS Software Using FTP or TFTP Without a Webserver

To install Junos OS software using FTP or TFTP:

  1. Uninstall the preinstalled Junos OS version.

    • Select Go to ONIE Loader from the GNU GRUB menu.

    • Select ONIE: Uninstall OS from the GNU GRUB menu.

    The Junos OS is uninstalled, and the switch reboots.

    By default, the ONIE discovery and execution (ODE) application attempts to discover and fetch an image from a configured webserver. If you do not have DHCP configured, you will need to stop the ONIE discovery and execution (ODE) application and manually configure static addressing for the management IP address of the switch,

    For example:

  2. Copy the Junos OS image to an FTP or TFTP directory.
  3. Issue the onie-nos-install command at the ONIE prompt to install the Junos OS software.

    If you are using FTP:

    If you are using TFTP:

    Note:

    The software image should be located in the /tftp/boot directory.

    The switch reboots and displays the GNU GRUB menu.

Installing Junos OS Software Using DHCP Server with No DHCP Options Configured

Use this installation method if you cannot modify or set the DHCP options on your DHCP server.

To install the Junos OS software using a DHCP server with no DHCP options configured:

  1. Copy the software image with the filename jnpr-qfx-5e-jdm-onie-updater-15.1-20150819_ups.4.bin to the var/www/html directory of the webserver or DHCP server.
  2. Uninstall the preinstalled Junos OS version.

    • Select Go to ONIE Loader from the GNU GRUB menu.

    • Select ONIE: Uninstall OS from the GNU GRUB menu.

    The Junos OS is uninstalled, and the switch reboots.

  3. Issue the onie-nos-install command at the ONIE prompt to install the Junos OS software.

    For example:

    Here is sample log with the options you just configured:

    This log shows that the installation process has fetched the Junos OS software image from the webserver and is installing the Junos OS software.

    The switch reboots and the GNU GRUB menu is displayed.

Installing Junos OS Software Using Webserver Without DHCP Configured

Use this installation method if you do not have a DHCP server.

To install the Junos OS software using a webserver without DHCP configured:

  1. Because the switch comes preinstalled with the Junos OS to be used with the Junos OS CLI, you need to uninstall this version of software before you can install the Junos OS image to be used with ONIE.

    • Select Go to ONIE Loader from the GNU GRUB menu.

    • Select ONIE: Uninstall OS from the GNU GRUB menu.

    The Junos OS is uninstalled, and the switch reboots.

  2. Select ONIE: Uninstall OS from the GNU GRUB menu.

    The Junos OS is uninstalled, and the switch reboots.

    By default, the ONIE discovery and execution (ODE) application attempts to discover and fetch an image from a configured webserver. Because you do not have DHCP configured, you will need to stop the ONIE discovery and execution (ODE) application and manually configure static addressing for the management IP address of the switch.

    For example:

  3. Copy the software image to the var/www/html directory of the webserver.
  4. Issue the onie-nos-install command at the ONIE prompt to install the Junos OS software.

    For example:

    Here is sample log:

    The log shows that the installation process has fetched the Junos OS software image from the webserver and is installing the Junos OS software.

    The switch reboots and the GNU GRUB menu is displayed.

Installing Junos OS Software Using USB Media

ONIE installation from a Junos OS image stored on USB media is not currently supported.

Use another procedure from this document to install ONIE.

Verifying Software Installation

Purpose

Verify that the software was installed successfully on the switch.

Action

To verify that the software was properly installed, issue the show version command.

Troubleshooting Boot Problems

Problem

Description

Junos OS does not boot.

Solution

If Junos OS does not boot, and the console displays the Yocto GNU Linux shell instead, it could mean that you have booted in the Juniper Linux Debug mode. If you see an error message that says, “[Error] Does not seem to be an QFX10002.” could mean that the EEPROM does not contain vendor-specific information. To verify the vendor-specific information, perform an ONIE: Rescue installation, and then verify the contents of the /var/run/*.dat file.

  1. Select ONIE: Rescue from the GNU GRUB menu.

  2. Issue the onie-syseeprom at the ONIE prompt.

    For example:

    From the output, you can see that the vendor-specific information confirms that it is for Juniper Networks.

Creating an Emergency Boot Device

Before you begin, you need to have the jnpr-qfx-5e-jdm-onie-updater-15.1-20150819_ups.4.bin version of ONIE software.

If the Open Network Install Environment (ONIE) software is damaged or corrupted in some way, or the switch went into rescue mode, you can use an emergency boot device to repartition the primary disk and load a fresh installation of ONIE. Use the following procedure to create an emergency boot device.

Note:

In the following procedure, we assume that you are creating the emergency boot device on a switch. You can create the emergency boot device on any PC or laptop that supports Linux.

To create an emergency boot device:

  1. Insert the USB device into the front USB port of the switch.

    Make sure the USB device is at least 1GB.

  2. Issue the following command from the directory on the switch in which the ISO file is located:

    You can also issue the dd command using the full path to where the ISO file is located.

    For example, if the ISO file is located in the /var/tmp/ directory:

    The switch writes the installation media image to the USB device:

  3. Remove the USB device from the USB port of the switch.

Performing a Recovery Installation

In the event that the Open Network Install Environment (ONIE) is corrupted, the switch goes into rescue mode, or you need to reinstall ONIE software for any reason, you need to perform a recovery installation.

Note:

All Junos OS partitions are destroyed during a recovery installation.

Note:

Before you can perform a recovery installation, make sure you have an emergency boot device loaded with ONIE software.

  1. Insert the emergency boot device into the device.

  2. Power cycle the device.

  3. Press the ESC button to go into the Boot Manager menu.

  4. Select Boot Manager, and then press Enter.

  5. Select Unigen PQS1000 under Legacy USB, and then press Enter.

  6. Select ONIE: Embed ONIE from the ONIE Installer menu, and then press Enter.

    The recovery installation proceeds using the emergency boot device.

  7. Remove the emergency boot device.

  8. Verify that the ONIE software was installed by looking at the installation log file.

    For example:

    Installation log files are displayed automatically during the installation process, but if you want to verify installation log files at a different time, you can find them in the in the /var/log/ directory. To view an installation log file, issue the tail -f /var/log/onie.log command.

  9. Issue the parted /dev/sda print command to verify that the ONIE partitions have been created.

    For example:

Related Documentation