Image Discovery and Execution

The primary responsibility of ONIE is to locate a network operating system (NOS) installer and execute it.

Platform Name and Identification

For identifying the running platform. ONIE uses the following definitions:

  • arch – The CPU architecture. The currently supported architectures are:
    • arm
    • powerpc
    • x86_64
  • machine – A string of the form <VENDOR>_<MODEL>.
  • machine-revision – A string of the form r<NUMBER>, used to track different hardware revision of a machine
  • platform – A string of the form <ARCH>-<MACHINE>-<MACHINE-REVISION>
  • switch-silicon-vendor – A string of one of the following, used to track ASIC silicon vendor:
Silicon Vendor String
Broadcom bcm
Cavium cavium
Centec centec
Marvell mvl
Mellanox mlnx
Nephos nephos
Qemu qemu

Note

The above definitions place some restrictions on the valid characters allowed for the <ARCH>, <VENDOR> and <MODEL> strings.

The allowable characters in the above strings are:

  1. VENDOR - cannot contain _ (underscore) or - (hyphen) characters
  2. MODEL - cannot contain - (hyphen) character. _ (underscore) is OK
  3. ARCH - cannot contain _ (underscore) or - (hyphen) characters

At runtime, ONIE provides the onie-sysinfo command, which can be used to dump this information and more. See the System Information section for more about the onie-sysinfo command.

The platform name must remain consistent across all ONIE modes as described in Network Operating System Interface.

Installer Discovery Methods

ONIE attempts to locate the installer through a number of discovery methods. The first successful method found is used to download and run an installer.

Note

Even though an installer is successfully found, the installer can fail, in which case ONIE moves on to the next discovery method.

The following methods are tried in this order:

  1. Statically configured (passed from boot loader)
  2. Local file systems (USB for example)
  3. Exact URLs from DHCPv4
  4. Inexact URLs based on DHCP responses
  5. IPv6 neighbors
  6. TFTP waterfall

Note

The discovery methods are tried repeatedly, forever, until a successful image install occurs.

The general image discovery procedure is illustrated by this pseudo-code:

while (true) {
  Configure Ethernet management console
  Attempt discovery method 1
  Attempt discovery method 2
  ...
  Attempt discovery method N
  Sleep for 20 seconds
}

The subsequent sections describe these methods in detail.

Default File Name Search Order

In a number of the following methods, ONIE searches for default file names in a specific order. All the methods use the same default file names and search order, which are described in this section.

The default installer file names are searched for in the following order:

  1. onie-installer-<arch>-<vendor>_<machine>-r<machine_revision>
  2. onie-installer-<arch>-<vendor>_<machine>-r<machine_revision>.bin *
  3. onie-installer-<arch>-<vendor>_<machine>
  4. onie-installer-<arch>-<vendor>_<machine>.bin *
  5. onie-installer-<vendor>_<machine>
  6. onie-installer-<vendor>_<machine>.bin *
  7. onie-installer-<cpu_arch>-<switch_silicon_vendor>
  8. onie-installer-<cpu_arch>-<switch_silicon_vendor>.bin *
  9. onie-installer-<arch>
  10. onie-installer-<arch>.bin *
  11. onie-installer
  12. onie-installer.bin *

Note

ONIE 2017.08 added the .bin extension to all the default file names. Previous ONIE versions do not look for file names with the .bin extension.

For a hypothetical x86_64 machine, the default installer file names would be:

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

Note

ONIE 2016.05 introduced onie-installer-<cpu_arch>-<switch_silicon_vendor>. All previous ONIE versions do not include this naming item.

Note

In the case of ONIE self-update mode, the file name prefix is onie-updater instead of onie-installer.

Note

For the exact file names used for your specific hardware platform please contact your NOS vendor or your hardware vendor.

Static Configuration Method

This method is intended for engineering use only; for example, during the porting of ONIE to a new platform. In the boot loader, the user can statically configure an installer URL that ONIE will use by setting the install_url kernel command line argument.

Local File System Method

In this method, ONIE searches the partitions of locally attached storage devices looking for one of the ONIE default installer file names.

See Default File Name Search Order for more information on the default file names.

This method is intended for the case where the NOS installer is available on a USB memory stick plugged into the front panel.

Two file system types are supported, the popular vFAT partition type (common on commercially availabe USB sticks) and Linux’s ext2.

Note

OSX’s Disk Utility by default will write out an unsupported partition type. Please use the diskutil command line tool for formatting:

# Find USB drive

% diskutil list
/dev/disk2
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:     FDisk_partition_scheme                        *8.1 GB     disk2
   1:               Windows_NTFS ONIE                    8.1 GB     disk2s1

# Write out correctly label (wipes all data on drive)

% sudo diskutil eraseDisk FAT32 ONIE MBRFormat /dev/disk2
Started erase on disk2
Unmounting disk
Creating the partition map
Waiting for the disks to reappear
Formatting disk2s1 as MS-DOS (FAT32) with name ONIE
512 bytes per physical sector
/dev/rdisk2s1: 15697944 sectors in 1962243 FAT32 clusters (4096 bytes/cluster)
bps=512 spc=8 res=32 nft=2 mid=0xf8 spt=32 hds=255 hid=2 drv=0x80 bsec=15728638 bspf=15331 rdcl=2 infs=1 bkbs=6
Mounting disk
Finished erase on disk2

The general algorithm for locating the installer on local storage proceeds as follows:

foreach $partition in /proc/partitions {
  if able to mount $partition then {
    if default file name exists {
      Add partition to found_list
    }
  }
}

foreach $partition in found_list {
  Run installer from $partition
}

Ethernet Management Port Configuration

In order to perform network based image discovery the Ethernet management console must first be configured. The following configuration methods are tried in order:

  1. Static configuration – Set via the ip kernel command line argument
  2. DHCPv6 – Planned, but not yet implemented
  3. DHCPv4
  4. Link Local IPv4 address (see RFC-3927)

The static configuration uses the ip Linux kernel command line argument.

DHCP Requests and Responses

DHCP provides a powerful and flexible mechanism for specifying the installer URL exactly. During the DHCP request, ONIE sets a number of options to help the DHCP server determine an appropriate response.

The following options are set during the request:

DHCP Request Options
Option Name ISC option-name RFC
60 Vendor Class Identifier vendor-class-identifier RFC 2132
77 User Class user-class RFC 2132
125 Vendor-Identifying Vendor-Specific Information vivso RFC 3925
55 Parameter Request List dhcp-parameter-request-list RFC 2132

Vendor Class Identifier – Option 60

The vendor class identifier option is the concatenation of two strings, separated by the colon : character:

  1. The static string onie_vendor
  2. <arch>-<vendor>_<machine>-r<machine_revision>

For example, using the example x86_64 machine, the string would be:

onie_vendor:x86_64-VENDOR_MACHINE-r0

Note

For the exact DHCP Vendor Class Identifier used for your specific hardware platform please contact your NOS vendor or your hardware vendor.

See the Platform Name and Identification table for more about the platform name.

User Class – Option 77

The user class option is set to the static string:

onie_dhcp_user_class

Vendor-Identifying Vendor-Specific Information (VIVSO)

The VIVSO option allows for custom option namespaces, where the namespace is identified by the 32-bit IANA Private Enterprise Number. ONIE currently uses the enterprise number 42623 to identify its custom namespace.

The option codes within the ONIE namespace have a size of 1 byte. The option payload length is also 1 byte.

Within this namespace, the following option codes are defined:

VIVSO Options
Option Code Name Type Example
1 Installer URL string http://10.0.1.205/nos_installer.bin
2 Updater URL string http://10.0.1.205/onie_update.bin
3 Platform Name string VENDOR_MACHINE
4 CPU Architecture string x86_64
5 Machine Revision string 0

See the Platform-Dependent Environment Variables table for more information about the platform name.

Parameter Request List – Option 55

The parameter request list option encodes a list of requested options. ONIE requests the following options:

DHCP Parameter Request List Options
Option Name ISC option-name Option Type RFC Example
1 Subnet Mask subnet-mask dotted quad 2132 255.255.255.0
3 Default Gateway routers dotted quad 2132 10.0.1.2
6 Domain Server domain-name-servers dotted quad 2132 10.0.1.2
7 Log Server log-servers dotted quad 2132 10.0.1.2
12 Hostname host-name   2132 switch-19
15 Domain Name domain-name string 2132 cumulusnetworks.com
42 NTP Servers ntp-servers dotted quad 2132 10.0.1.2
54 DHCP Server Identifier dhcp-server-identifier dotted quad 2132 10.0.1.2
66 TFTP Server Name tftp-server-name string 2132 behemoth01 (requires DNS)
67 TFTP Bootfile Name bootfile-name or filename string 2132 tftp/installer.sh
72 HTTP Server IP www-server dotted quad 2132 10.0.1.251
114 Default URL default-url string 3679 http://server/path/installer
150 TFTP Server IP Address next-server dotted quad 5859 10.50.1.200

HTTP Requests and HTTP Headers

All HTTP requests made by ONIE include a set of standard HTTP headers, which an HTTP CGI automation system could utilize. The headers sent on each HTTP request are:

HTTP Headers
Header Value Example
ONIE-SERIAL-NUMBER: Serial number XYZ123004
ONIE-ETH-ADDR: Management MAC address 08:9e:01:62:d1:93
ONIE-VENDOR-ID: 32-bit IANA Private Enterprise Number in decimal 12345
ONIE-MACHINE: <vendor>_<machine> VENDOR_MACHINE
ONIE-MACHINE-REV: <machine_revision> 0
ONIE-ARCH: CPU architecture x86_64
ONIE-SECURITY-KEY: Security key d3b07384d-ac-6238ad5ff00
ONIE-OPERATION: ONIE mode of operation os-install or onie-update

Exact Installer URLs From DHCPv4

The DHCP options discussed previously provide a number of ways to express the exact URL of the NOS installer. When interpreting URLs, ONIE accepts the following URI schemes:

  • http://server/path/….
  • ftp://server/path/….
  • tftp://server/path/….

The following options can be used to form an exact URL.

Exact DHCP URLs
Option Name Comments
125 VIVSO The installer URL option (code = 1) specified in the ONIE VIVSO. Options yields an exact URL. See Vendor-Identifying Vendor-Specific Information (VIVSO) above.
114 Default URL Intended for HTTP, but other URLs accepted.
150 + 67 TFTP server IP and TFTP bootfile Both options required for an exact URL.
66 + 67 TFTP server name and TFTP bootfile Both options required for an exact URL. Requires DNS.

Partial Installer URLs

Configuring a DHCP server for exact URLs may be impractical in certain situations.

For example, consider an enterprise scenario where the corporate IT department that controls the DHCP server is separate from the application development department trying to prototype new Web services. The application department wants to move quickly and prototype their new solution as soon as possible. In this case, waiting for the IT department to make DHCP server changes takes too much time.

To allow for flexibility in the administration of the DHCP server, ONIE can find an installer using partial DHCP information. ONIE uses a default sequence of URL paths and default installer file names in conjunction with partial DHCP information to find an installer.

See Default File Name Search Order for more information on the default file names and search order.

The following DHCP option responses are used to locate an installer in conjunction with the default file names:

Partial DHCP URLs
DHCP Options Name URL
67 TFTP Bootfile Contents of bootfile [1]
72 HTTP Server IP http://$http_server_ip/${onie_default_installer_names}
150 TFTP Server IP http://$tftp_server_ip/${onie_default_installer_names}
54 DHCP Server IP http://$dhcp_server_ip/${onie_default_installer_names}

Default ONIE image server name onie-server

If the default ONIE server name onie-server is resolvable by DNS it is included in the search for the default installer file names for both http and tftp protocols. The following URLs are attempted:

http://onie-server/${onie_default_installer_names}
tftp://onie-server/${onie_default_installer_names}

TFTP Waterfall

ONIE includes a classic PXE-like TFTP waterfall. Given a TFTP server address, ONIE attempts to download the installer using a sequence of TFTP paths with decreasing levels of specificity.

The TFTP URL name has this format:

tftp://$tftp_server_ip/$path_prefix/$onie_default_installer_name

The $tftp_server_ip comes from DHCP option 66.

The $path_prefix is determined in the following manner:

  1. First the path_prefix is built using the Ethernet management interface’s MAC address using lower case hexadecimal with a dash separator. For example, with address 55:66:AA:BB:CC:DD the path_prefix would be 55-66-aa-bb-cc-dd.
  2. Next, the path_prefix is built using the Ethernet management interface’s IP address in upper case hexadecimal. For example, 192.168.1.178 -> C0A801B2. If the installer is not found at that location, remove the least significant hex digit and try again.
  3. Finally, look for the list of default file names at the root of the TFTP server.

Here is a complete list of the bootfile paths attempted using the example MAC address, IP address and the example x86_64 platform:

55-66-aa-bb-cc-dd/onie-installer-<arch>-<vendor>_<machine>
C0A801B2/onie-installer-<arch>-<vendor>_<machine>
C0A801B/onie-installer-<arch>-<vendor>_<machine>
C0A801/onie-installer-<arch>-<vendor>_<machine>
C0A80/onie-installer-<arch>-<vendor>_<machine>
C0A8/onie-installer-<arch>-<vendor>_<machine>
C0A/onie-installer-<arch>-<vendor>_<machine>
C0/onie-installer-<arch>-<vendor>_<machine>
C/onie-installer-<arch>-<vendor>_<machine>
onie-installer-<arch>-<vendor>_<machine>-<machine_revision>
onie-installer-<arch>-<vendor>_<machine>
onie-installer-<vendor>_<machine>
onie-installer-<arch>
onie-installer

See Default File Name Search Order for more information on the default file names and search order.

HTTP IPv4 and IPv6 Neighbors

ONIE queries its IPv4 and IPv6 link-local neighbors via HTTP for an installer. The general algorithm follows:

  1. ping the IPv4 broadcast address, 255.255.255.255.
  2. ping6 the “all nodes” link local IPv6 multicast address, ff02::1.
  3. For each responding neighbor, try to download the default file names from the root of the HTTP server.

Here is an example of the URLs used by this method:

http://203.0.113.14/onie-installer-x86_64-VENDOR_MACHINE-r0
http://203.0.113.14/onie-installer-x86_64-VENDOR_MACHINE
http://203.0.113.14/onie-installer-VENDOR_MACHINE
http://203.0.113.14/onie-installer-x86_64
http://203.0.113.14/onie-installer
http://203.0.113.75/onie-installer-x86_64-VENDOR_MACHINE-r0
http://203.0.113.75/onie-installer-x86_64-VENDOR_MACHINE
http://203.0.113.75/onie-installer-VENDOR_MACHINE
http://203.0.113.75/onie-installer-x86_64
http://203.0.113.75/onie-installer
http://203.0.113.108/onie-installer-x86_64-VENDOR_MACHINE-r0
http://203.0.113.108/onie-installer-x86_64-VENDOR_MACHINE
http://203.0.113.108/onie-installer-VENDOR_MACHINE
http://203.0.113.108/onie-installer-x86_64
http://203.0.113.108/onie-installer
http://fe80::4638:39ff:fe00:139e%eth0/onie-installer-x86_64-VENDOR_MACHINE-r0
http://fe80::4638:39ff:fe00:139e%eth0/onie-installer-x86_64-VENDOR_MACHINE
http://fe80::4638:39ff:fe00:139e%eth0/onie-installer-VENDOR_MACHINE
http://fe80::4638:39ff:fe00:139e%eth0/onie-installer-x86_64
http://fe80::4638:39ff:fe00:139e%eth0/onie-installer
http://fe80::4638:39ff:fe00:2659%eth0/onie-installer-x86_64-VENDOR_MACHINE-r0
http://fe80::4638:39ff:fe00:2659%eth0/onie-installer-x86_64-VENDOR_MACHINE
http://fe80::4638:39ff:fe00:2659%eth0/onie-installer-VENDOR_MACHINE
http://fe80::4638:39ff:fe00:2659%eth0/onie-installer-x86_64
http://fe80::4638:39ff:fe00:2659%eth0/onie-installer
http://fe80::230:48ff:fe9f:1547%eth0/onie-installer-x86_64-VENDOR_MACHINE-r0
http://fe80::230:48ff:fe9f:1547%eth0/onie-installer-x86_64-VENDOR_MACHINE
http://fe80::230:48ff:fe9f:1547%eth0/onie-installer-VENDOR_MACHINE
http://fe80::230:48ff:fe9f:1547%eth0/onie-installer-x86_64
http://fe80::230:48ff:fe9f:1547%eth0/onie-installer

This makes it very simple to walk up to a switch and directly connect a laptop to the Ethernet management port and install from a local HTTP server.

See Default File Name Search Order for more information on the default file names and search order.

Execution Environment

After ONIE locates and downloads an installer, the next step is to run the installer.

Prior to execution, ONIE prepares an execution environment:

  • chmod +x on the downloaded installer.
  • Export a number of environment variables, usable by the installer.
  • Run the installer.

ONIE exports the following environment variables:

Installer Core Environment Variables
Variable Name Meaning
onie_exec_url Currently executing URL
onie_platform CPU architecture, vendor and machine name
onie_vendor_id 32-bit IANA Private Enterprise Number in decimal
onie_serial_num Device serial number
onie_eth_addr MAC address for Ethernet management port

In addition, any and all DHCP response options are exported, in the style of BusyBox’s udhcpc. A sample of those variables follows:

Installer DHCP Environment Variables
Variable Name Meaning
onie_disco_dns DNS Server
onie_disco_domain Domain name from DNS
onie_disco_hostname Switch hostname
onie_disco_interface Ethernet management interface, like eth0
onie_disco_ip Ethernet management IP address
onie_disco_router Gateway
onie_disco_serverid DHCP server IP
onie_disco_siaddr TFTP server IP
onie_disco_subnet IP netmask
onie_disco_vivso VIVSO option data

See Network Operating System Interface for more about the NOS installer.

Footnotes

[1]Try to intrepret the bootfile as a URL. This is a small abuse of the TFTP bootfile option, which has a precedent in other loading schemes such as iPXE.