RBFS Manual Installation

You can install RtBrick Host manually on an OCP-compliant bare-metal switch. The Open Network Install Environment (ONIE) is an open-source utility that provides an installation environment for OCP-compliant bare-metal switches. ONIE is used to install different network operating systems (NOS) on a device.

ONIE provides several methods for locating a Network Operating System (NOS) installer image. Detailed information about these methods can be found in the ONIE User Guide. The Host image can be installed using any of these methods.

  • If you are upgrading your existing RBFS installation, please refer to the section Upgrading the RBFS Image.

  • When installing Host, any existing configurations on the switch will be deleted.

  • The current RBFS configurations can be retrieved via a REST call from the RESTCONF endpoint. If you have saved the RBFS configuration using this method, you can load it onto the switch through a RESTCONF endpoint. For more information, refer to the following sections of the RtBrick documentation.

Prerequisites for Manual Installation

Installing RBFS Using a USB Thumb Drive

This section describes how to install image using a USB thumb drive.

Prerequisites

  • Format the USB drive with the FAT32 file system format because we need to place the RBFS image on the root directory of the USB drive.

  • Ensure that you have downloaded the RBFS Host image as described in the RBFS Image Download section.

Installation Procedure

You can also find instructions for installing via a USB thumb drive in the ONIE User Guide.

To install via USB, insert the USB drive to your computer and assume the USB drive appears as /dev/sda1 and is mounted at /media/rtbuser/4356-00B1 on Linux. This may vary depending on your system and operating system.

$ df -h
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1        29G   16K   29G   1% /media/rtbuser/4356-00B1

It is crucial to rename the RBFS Host image to onie-installer, as ONIE only recognizes images with this name at the root of the USB drive.

To install via USB, simply copy the installer image (in this example, the image name is bookworm-installer-multiservice-edge-q2c-s9600-72xc-25.3.1-candidate.2) to the root directory of the USB thumb drive, as shown below:

$ cp bookworm-installer-multiservice-edge-q2c-s9600-72xc-25.3.1-candidate.2 /media/rtbuser/4356-00B1/onie-installer

$ ls -al /media/rtbuser/4356-00B1/
total 1256820
drwxr-xr-x  2 rtbuser rtbuser      16384 Jan  1  1970 .
drwxr-x---+ 3 root     root           4096 Jan  9 11:49 ..
-rw-r--r--  1 rtbuser rtbuser 1286955159 Jan  9 11:49 onie-installer

  • Remove the USB drive from your computer and insert it into one of the USB ports on the front or rear panel of your ONIE-enabled device.

  • Insert the cable into the console port and connect to the console port of the device.

  • Power on the device and reboot it. ONIE will automatically detect the onie-installer file located at the root of the USB drive and execute it.

root@bl1-pod1:~# reboot

  • Wait for the device to show the "login:" prompt after installing the image. You can then log in and check the image version.

Manual Configuration of the Management Interface IP

If DHCP is not available, you need to manually configure the IP address, subnet mask, and default gateway for the device’s management port while still logged in from its console port.

  1. Identify the management port. Check the device documentation to determine which network interface is designated as the management interface (labeled "ma1").

  2. Modify the ma1 interface network parameters by adding IP address, Netmask, and gateway using your preferred editor. The example below shows how to modify these parameters using the Vim editor.

supervisor@host:/etc/network/interfaces.d $ vim ma1
auto ma1
iface ma1 inet static        <----- modify ma1 inet assignment as static
      address 192.0.2.187    <----- ma1 management interface ip address
      netmask 255.255.255.0  <----- subnet mask
      gateway 192.0.2.10     <----- configure gateway

  1. Restart the networking service by disabling and enabling the ma1 interface, as shown in the example below. By default, the default route will point to the gateway IP address.

sudo ifdown ma1
sudo ifup ma1

Installing over the Network

For all network installation scenarios, ONIE expects the NOS installer image to be available on the network via HTTP.

Prerequisites

  • Ensure that you have downloaded the RBFS Host image as described in the RBFS Image Download section.

  • Ensure that you have set up an HTTP server that will make available the downloaded images for ONIE to use.

Installation Procedure

You can also find instructions for installing the Host image over the network in the ONIE User Guide.

To install the RtBrick Host image over the network, perform the following steps:

On a fresh box, host prompt is not available, so skip to ONIE prompt section.

host prompt section:

Manually select ONIE boot mode

  1. Connect to the console port

  1. Reboot the device

root@bl1-pod1:~# reboot

  1. Select "ONIE: Install OS" from the next selection menu displayed.

 +----------------------------------------------------------------------------+
 |*ONIE: Install OS   <---- Select this one                                   |
 | ONIE: Rescue                                                               |
 | ONIE: Uninstall OS                                                         |
 | ONIE: Update ONIE                                                          |
 | ONIE: Embed ONIE                                                           |
 | RTB: Image-A Kernel                                                        |
 | RTB: Image-B Kernel                                                        |
 |                                                                            |
 |                                                                            |
 |                                                                            |
 |                                                                            |
 |                                                                            |
 +----------------------------------------------------------------------------+


      Use the ^ and v keys to select which entry is highlighted.
      Press enter to boot the selected OS, `e' to edit the commands
      before booting or `c' for a command-line.

  1. Wait for the ONIE:/ # prompt.

NOTICE: ONIE started in NOS install mode.  Install mode persists
NOTICE: until a NOS installer runs successfully.

** Installer Mode Enabled **
ONIE:/ #
ONIE:/ #
ONIE:/ #

Provide the URL of the Host installer image location.

onie-nos-install https://server.example.com/rtbrick.net/_/images/latest/rtbrick-host-installer/bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.2

Wait until the device displays the "login:" prompt after the image upgrade completes. You can then log into the device and verify the image version.

Managing RBFS After Installation

After RBFS installation, you can manage the RBFS on the host system. The following commands allow you to perform various actions such as rebooting an image and install another version of the software in the other partition of the image.

rtb-reboot

This command allows you to reboot the host installer with either RTB image A or image B. This is a temporary reboot of the selected image (it restarts the system using the specific image).

Syntax:

rtb-reboot [-p] [--no-reboot] [A | B| install | update | rescue | uninstall]

The command options and description are provided in the following table:

Attribute Description

-p

Sets the selected boot target permanently. It indicates every time the system reboots in the future, it will use this boot target unless you change it again.

--no-reboot

Prevents the system from rebooting immediately after setting the boot target. It is useful if you want to change the boot option but delay the reboot.

A

Boots the system using RTB Image-A Kernel (one of the two software image partitions).

B

Boots the system using RTB Image-B Kernel (the alternate image partition).

install

Boots into ONIE in Install mode to load a new operating system once.

update

Boots ONIE in 'Update' mode to update the ONIE software itself.

rescue

Boots ONIE in 'Rescue' mode for recovery and troubleshooting.

uninstall

Boots ONIE in Uninstall mode, which removes the installed operating system.

rtb-reboot A

If the host installer is running image B, use the command to rtb-reboot A to reboot the device and directly boots image A. This is a temporary reboot of the selected image (restarts the system using the specific image).

This does not require any further boot selection input. The following example shows the output of the rtb-eboot A command:

supervisor@host:~ $ sudo rtb-reboot A
Using GRUB partition: /dev/sda2
Setting one-time boot to: RTB: Image-A Kernel
System will reboot into A in 10 seconds.
Press Enter to reboot immediately or Ctrl+C to cancel.
Broadcast message from root@host on pts/0 (Fri 2025-09-12 12:41:48 UTC):
The system will reboot now!
         Stopping session-26.scope- Session 26 of User supervisor...
[  OK  ] Removed slice system-modpr…lice - Slice /system/modprobe.

rtb-reboot B

If the host installer is running image A, use the command to rtb-reboot B to reboot the device and directly boots image B. This is a temporary reboot of the selected image (restarts the system using the specific image).

This does not require any further boot selection input. The following example shows the output of the rtb-reboot B command:

supervisor@host:~ $ sudo rtb-reboot B
Using GRUB partition: /dev/sda2
Setting one-time boot to: RTB: Image-B Kernel
System will reboot into B in 10 seconds.
Press Enter to reboot immediately or Ctrl+C to cancel.
Broadcast message from root@host on pts/0 (Fri 2025-09-12 12:51:03 UTC):
The system will reboot now!
         Stopping session-2.scopeession 2 of User supervisor...
[  OK  ] Removed slice system-modpr…lice - Slice /system/modprobe.

rtb-install

Image partition enables the installation of two different software versions, one on Image A and another on Image B. If you installed the software on Image A, you can install a different version on Image B.

The rtb-install command allows you to install another version of the software on Image B (if you have already installed RBFS on Image A) using a specified file path or URL as the source location.

For example, if RTB image A is already in use, you can target RTB image B for installation using a URL as the source.

The following output is used to figure out which image partition is currently running, either Image A or Image B. This output shows image B (as highlighted) that indicates currently running image partition is Image B.

supervisor@host:/ $ ls -la /imag*
-rw------- 1 root root 2 Sep 19 05:59 /image-B

When you execute the rtb-install command, it downloads the image from the given URL, installs it automatically, and provides an acknowledgment message once the installation is complete. Afterward, the system prompts for a reboot for the new installation to take effect.

The following example shows the output of the rtb-install command:

supervisor@host:/ $  sudo rtb-install -i A -u http://pkg.rtbrick.net/_/images/latest/rtbrick-host-installer/bookworm-installer-multiservice-edge-q2a-s9510-28dc-Downloading file from http://pkg.rtbrick.net/_/images/latest/rtbrick-host-installer/bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.1...
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 1421M  100 1421M    0     0  7360k      0  0:03:17  0:03:17 --:--:-- 9467k
Starting the downloaded file with IMAGE=A...
Verifying archive integrity...  100%   SHA256 checksums are OK. All good.
Uncompressing bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.1  100%

installer started from within RTB-System
skipping partitioning...
creating ext4 filesystem on partition RTB-IMAGE-A
mke2fs 1.47.0 (5-Feb-2023)
/dev/sda6 contains a ext4 file system labelled 'RTB-IMAGE-A'
    last mounted on / on Fri Sep 12 13:22:37 2025
Discarding device blocks: done
Creating filesystem with 4194304 4k blocks and 1048576 inodes
Filesystem UUID: 65b409b3-4c51-41ba-9ff5-51ce6dfbf16e
Superblock backups stored on blocks:
    32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632, 2654208,
    4096000

Allocating group tables: done
Writing inode tables: done
Creating journal (32768 blocks): done
Writing superblocks and filesystem accounting information: done

tune2fs 1.47.0 (5-Feb-2023)
installation to Image-A partition
[ 3345.852798] EXT4-fs (sda6): mounted filesystem with ordered data mode. Quota mode: none.
extracting image to /mnt/tmp.72RKIWi8Bj...
...finished
DEBUG: A
A: setting 65b409b3-4c51-41ba-9ff5-51ce6dfbf16e in /mnt/tmp.72RKIWi8Bj/etc/fstab
mount: (hint) your fstab has been modified, but systemd still uses
       the old version; use 'systemctl daemon-reload' to reload.
found ma1 interface, creating udev rule
installing grub bootloader...
unmounting partitions...
[ 3412.562356] EXT4-fs (sda6): unmounting filesystem.
finished installation!
please reboot the system

The installation is now complete. You can proceed with a reboot to apply the changes. The following example shows the output of the reboot command:

supervisor@host:/ $ sudo reboot
Broadcast message from root@host on pts/0 (Fri 2025-09-12 14:40:37 UTC):
The system will reboot now!

supervisor@host:/ $ [  OK  ] Stopped   OK  ] Removed slice system-modpr…lice - Slice /system/modprobe.
[  OK  ] Stopped target graphical.target - Graphical Interface.
[  OK  ] Stopped target rpcbind.target - RPC Port Mapper.

After the reboot, then the login prompt will be shown as below,

[  OK  ] Reached target graphical.target - Graphical Interface.
         Starting systemd-update-ut… Record Runlevel Change in UTMP...
[  OK  ] Finished systemd-update-ut… - Record Runlevel Change in UTMP.
Debian GNU/Linux 12 host ttyS0
host login: [   37.241798] device ma1 entered promiscuous mode
[   37.398983] device ma1 left promiscuous mode

host login:

Upgrading RBFS

This section describes the process for upgrading your current version of RBFS.

If you are performing a fresh installation on an OCP-compliant bare-metal switch, refer to the section RBFS Manual Installation.

Guidelines

  • When installing Host, any existing configurations on the switch will be deleted.

  • The current RBFS configurations can be retrieved via a REST call from the RESTCONF endpoint. If you have saved the RBFS configuration using this method, you can load it onto the switch through a RESTCONF endpoint. For more information, refer to the following sections of the RtBrick documentation.

Upgrading RBFS Using a Thumb Drive

Prerequisites

  • Format the USB drive with the FAT32 file system format because we need to place the RBFS image on the root directory of the USB drive.

  • Ensure you have downloaded the RtBrick host image described in the RBFS Image Download section.

You can also find instructions for installing via a USB thumb drive in the ONIE User Guide.

To install via USB, perform the following steps:

  • Insert the USB drive to your computer and assume the USB drive appears as /dev/sda1 and is mounted at /media/rtbuser/4356-00B1 on Linux. This may vary depending on your system and operating system.

$ df -h
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1        29G   16K   29G   1% /media/rtbuser/4356-00B1
Ensure that you rename the RtBrick Host image to onie-installer, as ONIE only recognizes images with this name at the root of the USB drive.

  • Copy the RBFS image (in this example, the RBFS image name is rtbrick-host-installer-accessleaf-q2c-s9600-102xc-24.9.1-candidate.16.d) to the root directory of the USB thumb drive, as shown below:

$ cp rtbrick-host-installer-accessleaf-q2c-s9600-102xc-24.9.1-candidate.16.d /media/rtbuser/4356-00B1/onie-installer
$ ls -al /media/rtbuser/4356-00B1/
total 1256820
drwxr-xr-x  2 rtbuser rtbuser      16384 Jan  1  1970 .
drwxr-x---+ 3 root     root           4096 Jan  9 11:49 ..
-rw-r--r--  1 rtbuser rtbuser 1286955159 Jan  9 11:49 onie-installer

  • Remove the USB drive from your computer and insert it into one of the USB ports on the front or rear panel of your ONIE-enabled device.

  • Connect to the console port.

  • Reboot the device.

root@bl1-pod1:~# reboot

Select "ONIE: Install OS" from the next selection menu displayed.

                    GNU GRUB  version 2.02
 +----------------------------------------------------------------------------+
 |*ONIE: Install OS   <----- Select this one                                  |
 | ONIE: Rescue                                                               |
 | ONIE: Uninstall OS                                                         |
 | ONIE: Update ONIE                                                          |
 | ONIE: Embed ONIE                                                           |
 +----------------------------------------------------------------------------+

      Use the ^ and v keys to select which entry is highlighted.
      Press enter to boot the selected OS, `e' to edit the commands
      before booting or `c' for a command-line.

ONIE will automatically detect the onie-installer file located at the root of the USB drive and execute it.

  • Wait until the device displays the "login:" prompt after the image upgrade completes. You can then log into the device and verify the image version.

The default username is “supervisor”, and the password is “supervisor”.