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 preinstalled 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.
If you want to use the Junos OS CLI to install software, see Installing Software Packages on QFX Series Devices.
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.
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:
- Using a Web browser, navigate to the https://support.juniper.net.
- Either click View all products> and select the product you are downloading software for, or type the product name.
- Find the package you want and click the item in the Downloads
column.
A login screen appears.
- Enter your name and password and press Enter.
- Read the End User License Agreement, click the I agree radio button, and then click Proceed.
- 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.
- 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:
user@switch# save filename 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:
- 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 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:
ONIE:/ # onie-discovery-stopONIE:/ # ifconfig eth0 10.204.32.96 netmask 255.255.254.0ONIE:/ # route add default gw 10.204.47.254To restart the ONIE discovery and execution (ODE) application, issue the onie-discovery-start command.
For example:
ONIE:/ # onie-discovery-start
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:
- Copy the software image with the filename onie-installer to the
var/www/htmldirectory of the webserver or DHCP server. - Configure the DHCP option 114 in the DHCP server to redirect to the webserver to fetch the Junos OS software image.
- 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.
- Configure DHCP option 114 and other DHCP options as necessary.
Here is a sample Windows Open DHCP server configuration with DHCP option 114 configured.
#Following are range-specific DHCP options. #You can copy more option names from [GLOBAL_OPTIONS] IP=10.204.42.250 SubnetMask=255.255.240.0 Router=10.204.47.254 114="http://10.207.66.147/onie-installer"
Here is a sample boot initialization log, showing the options you just configured:
Info: Trying DHCPv4 on interface: eth0 ONIE: Using DHCPv4 addr: eth0: 10.204.42.250 / 255.255.240.0 ONIE: Starting ONIE Service Discovery Info: Fetching http://10.207.66.147/onie-installer ... ONIE: Executing installer: http://10.207.66.147/onie-installer <<<<<<---- automatically redirects to web sever to fetch Junos OS image. Verifying image checksum ... OK. Preparing image archive ... OK. Installing Juniper NOS...
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:
- 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:
ONIE:/ # onie-discovery-stopONIE:/ # ifconfig eth0 10.204.32.96 netmask 255.255.254.0ONIE:/ # route add default gw 10.204.47.254 - Use SCP to copy the Junos OS image from a server or other
location to the
/var/tmpdirectory on the switch.For example:
user@server scp jnpr-qfx-5e-jdm-onie-updater-15.1-20150819_ups.4.bin root@10.204.32.196:/var/tmp/ - Issue the onie-nos-install command
in the
/var/tmpdirectory to install Junos OS software.ONIE:/var/tmp # onie-nos-install file:///var/tmp/jnpr-qfx-5e-jdm-onie-updater-15.1-20150819_ups.4.binThe 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:
- 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:
ONIE:/ # onie-discovery-stopONIE:/ # ifconfig eth0 10.204.32.96 netmask 255.255.254.0ONIE:/ # route add default gw 10.204.47.254 - Copy the Junos OS image to an FTP or TFTP directory.
- Issue the onie-nos-install command
at the ONIE prompt to install the Junos OS software.
If you are using FTP:
ONIE:/ # onie-nos-install ftp://<username>:<password>@10.209.152.22/jnpr-qfx-5e-jdm-onie-updater-15.1-20150819_ups.4.binIf you are using TFTP:
Note The software image should be located in the
/tftp/bootdirectory.ONIE:/ # onie-nos-install tftp://10.207.66.147/jnpr-qfx-5e-jdm-onie-updater-15.1-20150819_ups.4.binThe 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:
- Copy the software image with the filename jnpr-qfx-5e-jdm-onie-updater-15.1-20150819_ups.4.bin to the
var/www/htmldirectory of the webserver or DHCP server. - 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.
- Issue the onie-nos-install command at the ONIE
prompt to install the Junos OS software.
For example:
ONIE:/ # onie-nos-install http://10.207.66.147/jnpr-qfx-5e-jdm-onie-updater-15.1-20150819_ups.4.binHere is sample log with the options you just configured:
ONIE:/ # ifconfigeth0 Link encap:Ethernet HWaddr 94:DE:80:AA:F2:E1 inet addr:10.204.42.250 Bcast:10.204.47.255 Mask:255.255.240.0 <<<---- --> Received IP address from DHCP server, but auto redirected to web server. Installation will not happen because DHCP option (114) is not configured. inet6 addr: fe80::96de:80ff:feaa:f2e1/64 Scope:Link UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 RX packets:444 errors:0 dropped:0 overruns:0 frame:0 TX packets:17 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:1000 RX bytes:48170 (47.0 KiB) TX bytes:2678 (2.6 KiB) Memory:80180000-801a0000This log shows that the installation process has fetched the Junos OS software image from the webserver and is installing the Junos OS software.
Stopping: discover... done. Info: Fetching http://10.207.66.147/jinstall-qfx-10-f-15.1X53-D10.7-domestic-signed.tgz ... Connecting to 10.207.66.147 (10.207.66.147:80) installer 100% |*******************************| 464M 0:00:00 ETA ONIE: Executing installer: http://10.207.66.147/jnpr-qfx-5e-jdm-onie-updater-15.1-20150819_ups.4.bin Verifying image checksum ... OK. Preparing image archive ... OK. Installing Juniper NOS...
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:
- 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.
- 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:
ONIE:/ # onie-discovery-stopONIE:/ # ifconfig eth0 10.204.32.96 netmask 255.255.254.0ONIE:/ # route add default gw 10.204.47.254 - Copy the software image to the
var/www/htmldirectory of the webserver. - Issue the onie-nos-install command at the ONIE
prompt to install the Junos OS software.
For example:
ONIE:/ # onie-nos-install http://10.204.35.100/jnpr-qfx-5e-jdm-onie-updater-15.1-20150819_ups.4.binHere is sample log:
Stopping: discover... done. Info: Fetching http://10.204.35.100/jnpr-qfx-5e-jdm-onie-updater-15.1-20150819_ups.4.bin ... Connecting to 10.204.35.100 (10.204.35.100:80) installer 100% |*******************************| 464M 0:00:00 ETA ONIE: Executing installer: http://10.204.35.100/jnpr-qfx-5e-jdm-onie-updater-15.1-20150819_ups.4.bin Verifying image checksum ... OK. Preparing image archive ... OK. Installing Juniper NOS...
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.
user@switch > show versionTroubleshooting 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.
- Select ONIE: Rescue from the GNU GRUB menu.
- Issue the onie-syseeprom at
the ONIE prompt.
For example:
ONIE:/ # onie-syseepromTlvInfo Header: Id String: TlvInfo Version: 1 Total Length: 315 TLV Name Code Len Value -------------------- ---- --- ----- Base MAC Address 0x24 6 54:2A:A2:FB:DC:00 MAC Addresses 0x2A 2 256 Product Name 0x21 23 QFX10000-ÿÿÿÿÿÿÿ Serial Number 0x23 12 116G1EC00032 Part Number 0x22 16 1AES48S6Q.A2Gÿÿÿ Device Version 0x26 1 1 Manufacture Date 0x25 19 01/13/2015 21:40:30 Vendor Name 0x2D 20 JUNIPER NETWORKS INC Manufacturer 0x2B 14 JUNIPER NETWORKS INC Vendor Extension 0xFD 48 0x00 0x00 0x7C 0x82 0x01 0x00 0x41 0x32 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0x0F Vendor Extension 0xFD 62 0x00 0x00 0x0A 0x4C 0x51 0x06 0x52 0x45 0x56 0x20 0x30 0x31 0x52 0x0C 0x3F Platform Name 0x28 37 x86_64-alpha_networks_snx60a0_486f-r0 Loader Version 0x29 23 master-201412161452.0.1 CRC-32 0xFE 4 0xB88C8885 Checksum is valid.
From the output, you can see that the vendor-specific information confirms that it is for Juniper Networks.
Creating an Emergency Boot Device
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.
Before you begin, you need to have the jnpr-qfx-5e-jdm-onie-updater-15.1-20150819_ups.4.bin version of ONIE software.
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:
- Insert the USB device into the front USB port of the switch.
Make sure the USB device is at least 1GB.
- Issue the following command from the directory on the
switch in which the ISO file is located:
ONIE:/ # jnpr-qfx-5e-jdm-onie-updater-15.1-20150819_ups.4.bin of=<usb-detected-drive> bs=1MYou 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:
ONIE:/ # dd if=/var/tmp/jnpr-qfx-5e-jdm-onie-updater-15.1-20150819_ups.4.bin of=<usb-detected-drive> bs=1MThe switch writes the installation media image to the USB device:
- 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.
All Junos OS partitions are destroyed during a recovery installation.
Before you can perform a recovery installation, make sure you have an emergency boot device loaded with ONIE software.
Insert the emergency boot device into the device.
Power cycle the device.
Press the ESC button to go into the Boot Manager menu.
Select Boot Manager, and then press Enter.
Select Unigen PQS1000 under Legacy USB, and then press Enter.
Select ONIE: Embed ONIE from the ONIE Installer menu, and then press Enter.
The recovery installation proceeds using the emergency boot device.
Remove the emergency boot device.
Verify that the ONIE software was installed by looking at the installation log file.
For example:
Info: Found static url: file:///lib/onie/onie-updater ONIE: Executing installer: file:///lib/onie/onie-updater Verifying image checksum ... OK. Preparing image archive ... OK. ONIE: Version : master-201412161452.0.1
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.Issue the parted /dev/sda print command to verify that the ONIE partitions have been created.
For example:
ONIE:/ # parted /dev/sda printModel: ATA TS8GHSD630 (scsi) Disk /dev/sda: 8012MB Sector size (logical/physical): 512B/512B Partition Table: gpt Disk Flags: Number Start End Size File system Name Flags 1 1049kB 3146kB 2097kB GRUB-BOOT hidden, bios_grub 2 3146kB 137MB 134MB ext4 ONIE-BOOT hidden