Now that we have established access to our switch, we are ready to install an operating system on it. This chapter will show us how this can be done. We will first have a look at the Open Network Install Environment, ONIE, and will then learn how the actual SONiC installation works.

What is ONIE?
Before we begin with the actual switch installation, let’s have a look at the ONIE bootloader, which comes with every bare metal switch, and learn what it does.

ONIE stands for Open Network Install Environment. Its purpose is to facilitate installing and uninstalling real switch operating systems on a bare metal switch. It is a project maintained by the OCP, the Open Compute Project Foundation. ONIE itself is often called a bootloader, but in fact, it is a small operating system itself. It is built on a Linux kernel with BusyBox, an environment for small embedded systems, to keep it compact.

The operating systems that can be installed on a bare metal switch come in the shape of ONIE installers. These are self-extracting archives that are executed by the ONIE install environment. For SONiC too, ONIE installers are available in many flavors.

ONIE makes it very easy to install an OS on one switch or on many switches. It has many hooks for automation that allow installation of an OS on a switch without manual intervention, which is what we call zero-touch provisioning, or ZTP. You can find more information about ONIE on the website of the OCP if you follow the link on the slide.

ONIE modes
As we have mentioned, ONIE comes with every bare metal switch. It is pre-installed on a small partition on the switch storage and normally remains there. Other operating systems are usually installed in partitions next to this one.

If no other OS is installed on the switch, ONIE boots its install mode when the switch is powered up. In this mode, ONIE will continuously look for installer images locally and on the network. It uses a predefined algorithm to search the local file system, potential USB sticks, or the network via the HTTP or TFTP protocols. In addition, you can use DHCP to supply a URL to the switch pointing to an installer image. If you don’t want to set up a bunch of servers just to install a handful of switches, you can also choose to execute an installer manually. You can supply ONIE with a local file name or a URL to find an installer image that it should execute.

The actual installation process is usually automatic, and you can just sit and watch how it progresses. Once it is finished, one of the last actions of the installer is to set up the boot selector, GRUB, so that after the following reboot, the switch will boot into the newly installed OS. ONIE will remain in the GRUB menu as an alternative choice. The switch will now automatically reboot, and eventually, you should see the login prompt of the installed operating system.

While installing an OS is the main functionality of ONIE, you have more options. What you installed may at some point have to be uninstalled again, so there is also an uninstall mode. The uninstall process is started automatically when the uninstall mode is selected for booting. It is very thorough in its operation, wiping and zeroing out the complete permanent storage of the switch. All partitions except the ONIE partition will be erased. Since the whole storage is overwritten, this uninstall process will take a significant amount of time, depending on the size of the partitions that are there. Once it is finished, the switch will automatically reboot into the ONIE install mode, and you can install a new OS.

There is also a rescue mode that is, as the name implies, not used for normal operation, but rather to troubleshoot or repair certain things. It looks like the install mode, except that the automatic install process is not started. You could, for example, use this mode to break into the switch if you have forgotten the OS password.

Finally, there is an embed ONIE mode that you can find if you boot from a USB stick containing an ONIE image for the switch. This can be used to maintain ONIE itself, that is, to repair a broken ONIE or to update it. These images can be obtained from the switch vendor.

Now that we know how we can use ONIE to install an open networking OS, we are ready to install SONiC on our switch.

Installation options
As mentioned before, ONIE gives us different options to install an OS on a switch. Using the automated installations, we can install an OS on an arbitrary number of switches without manual intervention. We just have to prepare our ONIE or DHCP servers once and can have each new switch use them. The manual installation may be easier if you only have to install a small number of switches and don’t want to set up any servers just for that. It could also be used to install a special image on a particular switch, for example.

For the automated installation, there are again two options. The first one uses the integrated ONIE discovery method. This looks for a specific HTTP or TFTP server and for special image names on that server. These file names depend on the switch type and are thus vendor-dependent. The other automated install option uses DHCP to receive a default URL from the DHCP server. This URL points to the installer image to be used. For both automated install methods, if a valid installer image can be downloaded, the installation will begin automatically.

The manual installation is quite easy too. You have to enter the command onie-nos-install and supply it with an installer URL or local file name. A local file name could point to an installer file that you have previously uploaded to the switch by some other means, or to a file on a mounted USB pen drive.

All these options don’t just apply to an installation of SONiC, but to any OS for which you have obtained an ONIE installer image. Let’s now have a closer look at how the various installation options work in detail.

The ONIE EEPROM
You may want to use different OS images depending on the type of switch or even a particular switch. ONIE maintains an EEPROM space that contains information about the switch that can and will be used by the automated installation options to help identify the switch or type of switch. For example, it contains the platform name, product name, serial number, and base MAC address of the switch.

The ONIE discovery process uses this information to construct potential installer file names that it tries to download. The DHCP client uses the information to provide a client identifier in its DHCP requests.

You can check the contents of this EEPROM using the onie-syseeprom command. As we will see in the troubleshooting module of this training, the information can also be queried when the switch is running SONiC. There’s also an onie-sysinfo command that will only display the platform name.

ONIE discovery
Now we are ready to look at the actual installation methods. First, we will examine the ONIE discovery algorithm to find an installer image. The process is automatically started when ONIE install mode is booted and repeats every 20 seconds until an installer image is found. The process can be stopped with the onie-stop command or restarted with the onie-start command. In older versions of ONIE, these commands were named onie-discovery-stop and onie-discovery-start, respectively.

The ONIE discovery process will look for an HTTP or TFTP server called onie-server. This host name obviously needs to be resolved by a name server, which also means that ONIE must have received a DNS server address by DHCP previously. ONIE will also try to find HTTP or TFTP servers in the same VLAN by sending broadcast pings, both IPv4 and IPv6, and trying HTTP and TFTP access to each host that responds.

If ONIE has found a server, it will now look for images on that server following a standard image name pattern. These names start with onie-installer and contain switch-specific parts like the machine architecture, switch vendor, and switch type. This information is taken from the ONIE EEPROM that we have just learned about. The complete list of file names that are tried can be found in the ONIE documentation.

All of these steps are tried with every iteration of the discovery process, every 20 seconds. So it is never too late to set up your ONIE server and adjust the configuration if something is not right, for example, if the access rights of your TFTP file don’t allow global read access. Once ONIE has managed to download a valid installer image from some server, the installation will begin automatically.

Installation via DHCP
An automated installation option that is a little more flexible relies on the DHCP server to convey the installer image URL to the switch. ONIE will use DHCP anyway to obtain an IP address for the management interface of the switch. With the offer from the server, a default URL option can be sent. ONIE will try to access this URL and download the image pointed to by the URL.

ONIE will also help the DHCP server to send the proper URL for the correct installer image by sending switch-specific information in its DHCP request. Again, this information is taken from the ONIE EEPROM. The switch type is encoded both in DHCP option 60, the vendor class identifier, and option 125, the vendor-identifying vendor-specific information, or VIVSO for short. Again, if ONIE can download a valid installer image from the URL it has received, the installation will begin automatically.

Here we see an example of a simple DHCP server configuration file. The first snippet shows the subnet declaration defining the IP address pool, subnet mask, gateway, and name server. Here we can already put our default URL option, which would then of course be sent to each device connecting to that subnet. We can also add a host-specific configuration based on the MAC address of the management port of our switch, so that only this switch will receive the default URL. We could also add a class configuration matching only the ONIE devices of the desired kind and so supply a different URL per switch type. This configuration will become a little lengthy, so we refer you to the ONIE documentation for examples.

Manual installation
After we have explored the automated install options, let’s now have a look at how to do a manual install. Our first example shows how to pull an installer file from an HTTP, FTP, or TFTP server. This could be an internal one, or if your internet connection from the switch works and you