Table Of Contents

Contents

  1. Home
  2. Design Specification
  3. Operating Software Design
  4. Image Discovery and Execution

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.

Linux Kernel Configuration
Network Operating System Interface
© Copyright 2013-2018, Cumulus Networks, Inc. All Rights Reserved.