RBFS Installation, ZTP, and Licensing Guide

The RBFS software is available for different roles based on their functions. RBFS C-BNG, Spine, Leaf and L2BSA images are stored in the RBFS image repository from where users can download and install the images on the supported hardware platforms. When new features and software patches become available in the image store, you can upgrade the software to use them. All the latest versions of software images are stored in the RBFS image store.

The RBFS software is delivered as custom RtBrick Linux container images (also called RBFS container images) which can be used for virtual topologies on x86 servers or as custom RtBrick ONL installer images that can be used on the supported white box switches.

Image stores containing the container and ONL installer images are published on https://releases.rtbrick.com/ and updated when new image versions are available.

In addition to RBFS, other RtBrick software is delivered in the Debian package format that can be used on Ubuntu. Currently, the only supported Ubuntu release is 22.04 LTS Jammy. This category of software is referred to RtBrick Tools. The software delivered as Debian packages is composed of a set of CLI tools and/or daemons intended to facilitate working with RBFS containers and the RBFS API.

Debian package repositories containing the packages are available on https://releases.rtbrick.com/ and updated whenever a new version of the package is available.

The RtBrick managed software download functionality enables authenticated users to download and install the RtBrick software (packages or images). Access to image stores and Debian package repositories on https://releases.rtbrick.com/
is restricted through the use of TLS mutual authentication with TLS client certificates (TLS client certificates can be self-signed).

To access the restricted image stores and Debian package repositories on https://releases.rtbrick.com/, perform the following steps:

RtBrick provides the rtb-apt tools to generate a client certificate. For more information, see the section The RtBrick APT tool (rtb-apt).

The rtb-apt tool is an APT (https://wiki.debian.org/Apt)
utility application that provides an easier way for managing the system configuration of RtBrick package repositories (https://wiki.debian.org/DebianRepository)
which can be used with the usual apt commands to install RtBrick software.

Some RtBrick package repositories require authentication via TLS client certificates and the rtb-apt tool provides commands for managing those specific repositories and the required apt authentication configuration.

The rtb-apt tool is a statically compiled Linux 64-bit executable file. Currently, it is verified to run on Ubuntu 22.04. It is available through a direct download link.

The RtBrick tools are distributed in the Debian (apt) package format in one of the rtbrick-tools debian (apt) package repositories as described in the RtBrick Tools Installation Guide section 1.3 step 3.

An RBFS release can be defined as a set of software packages (currently, in the Debian package format). However, it is delivered as an image, either a container (LXC/LXD) image or as a complete ONL installation image. The ONL installation image may or may not contain a container image pre-installed in it. An image can be defined as the archived root file system of a Linux OS installation with the needed software packages pre-installed and with a default configuration. In the current context, the terms 'RBFS release' and 'image' are used interchangeably.

RtBrick uses a versioning scheme called rtbver for RBFS release versioning. An rtbver version string is syntactically similar to SEMVER 2.0, but semantically different. For the RBFS releases, the first two numbers of a version is YEAR.MONTH (corresponding to the MAJOR.MINOR of SEMVER). For example, the first RBFS release in a calendar month is 22.4.1. If a second RBFS release occurs in the same calendar month gets version as 22.4.2. The RBFS release in the next calendar month will have a version (for example) 22.5.1 irrespective of how many RBFS releases occurred in the previous calendar month.

The rtbver scheme also supports four-number versioning, such as 22.4.1.1. This four-number version is used for maintenance releases. Maintenance releases are built only when required, based on and for an already existing RBFS release (such as 22.4.1.1 for 22.4.1.).

The installation of RtBrick tools is split into several steps, as follows:

Some of the RtBrick tools Debian packages have changed and have been upgraded several times. If any of the RtBrick tools packages are already installed, it is essential to remove any existing package.

apt list --installed | egrep -i rtbrick | awk -F '/' '{print $1;}' | xargs sudo apt remove -y

In the output, you can see the following:

The following packages are removed.

Update the local apt package cache using the command: sudo apt update

Some RtBrick tools or packages have dependencies on third-party software such as Ansible. These third-party software packages are not delivered through the RtBrick package repositories.

Currently, the rtbrick-ansible package depends on Ansible software. For information about installing Ansible, see https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-on-ubuntu.

Install a particular RtBrick tool package, run the command:

sudo apt install <tool name>

For example, to install the rtbrick-ansible package, run the following command:

sudo apt install rtbrick-ansible

RtBrick images delivered through the RtBrick image store and the rtb-image utility have three main attributes:

RtBrick images intended to be used as containers in a virtualized environment contains format == lxd and platform == virtual.

RtBrick images intended to be installed on supported hardware devices contain format == onl-installer and platform set accordingly to the specific switching hardware.

The rtb-ssh command allows you to connect to a container that is already running.

The command was previously called rssh, and it was renamed as it confused with Linux’s restricted shell rssh package which is available in the official Ubuntu apt package repositories.

Besides renaming, a few changes have been made to the rtb-ssh / rssh script.

The script is installed automatically as part of the rtbrick-imgstore package installation.

The script uses lxc-attach to establish a connection to the container specified as the argument. While doing so, it uses the ubuntu user (currently, the default user inside an RBFS container) to connect to the container, and uses the bash shell after opening the connection.

Before connecting, it clears the environment before attaching, so no undesired environment variables leak into the container. The variable container=lxc is the only environment with which the attached program starts.

It only keeps the TERM variable, to have the same strings the user is currently using for clear screen, move cursor, and so on.

The rtb-ssh is installed in the /usr/local/bin/ path (alongside rtb-image, etc.). For convenience and backward compatibility the script is still also installed as rssh.

You can install open network Linux (ONL) manually on a bare-metal switch. Open Network Install Environment (ONIE) should be installed on the switch. The Open Network Install Environment (ONIE) is an open-source utility that provides an installation environment for bare-metal switches. ONIE is used to install different network operating systems (NOS) on a device.

The RtBrick ONL installer images are compatible with ONIE and can be used by ONIE to install an RtBrick ONL (Open Network Linux) on a bare-metal switch.

Zero Touch Provisioning (ZTP) automates the tasks of installing software images. It is a method for setting up and configuring devices automatically. ZTP installs or upgrades the RBFS software image on your hardware platforms without any manual intervention.

ZTP automatically provisions routers newly installed in the network and it is very useful in deploying routers in a large-scale environment as it eliminates much of the manual intervention. ZTP is also used to automate the software upgrade process and help with a high level of network automation.

A new hardware platform comes pre-installed with the ONIE (Open Network Installation Environment). ONIE is an open-source installation environment that acts as an enhanced boot loader utilizing capabilities in a Linux or BusyBox environment. ONIE allows users and channel partners to install the Network Operating System as part of provisioning.

ONIE requires a management LAN to obtain the configuration and software image information through the management interface. ONIE can access only the management interface. It starts a Dynamic Host Configuration Protocol (DHCP) based discovery process to obtain basic configuration information, such as the management IP address and the URL of the image to install on the bare-metal switch.

Then ONIE pulls the image and boots it.

Even after ONIE boots the image, the switch is not configured. This leads to questions about how to configure the switch.

The RtBrick images come with some pre-installed daemons. The pre-installed Control Daemon (CtrlD) is responsible for the management of the switch, and takes over after the image is activated.

The Control Daemon is responsible for configuring the switch. To do this, the hardware platform must be connected to the DHCP server and the management server through a management LAN.

The management server is responsible for providing the image binaries and the configuration of each device.

In the ZTP, ONIE performs the role of discovering, downloading and activating the image from the image registry.

In essence, the following is the high-level workflow of ZTP process:

ONIE performs the following tasks:

Control Daemon performs the following tasks:

ONIE allows to automate the firmware update. The image request to the management server is slightly different, and the management server needs to provide the firmware update image that the device vendor provides.

This section provides information about the NOS installation and firmware (FW) update.

Because of its low set of requirements, the default DHCP server shipped with ubuntu, isc-dhcp, is used to run the DHCP service.

The following code shows an example configuration of a DHCP server and hardware box (dhcp.conf).

Most of the used options are already predefined in the ISC-DHCP server. You can see the reference under /ISCKB/, the loader-pathprefix is defined since DHCP 4.4, so if you use an older one, define it as described above.

The HTTP daemon (httpd) is responsible for providing the NOS installer and the configuration files.

Therefore, a self-implemented Golang HTTP server is used, which reads the ONIE_SERIAL_NUMBER and ONIE-OPERATION HTTP header and maps them to the NOS/FW installer image download path, and maps the serial number to the ZTP configuration files. For more details about the configuration files, see the following section.

The ONIE-OPERATION header can have the following values:

The following sections provide information about the installation and configuration of the server.

Once the RBFS image is activated by ONIE, Control Daemon (CtrlD) is responsible for executing the remaining tasks and configuring the switch. CtrlD acts as a post-ZTP demon, it runs after the image is activated.

There are various configuration files that CtrlD can load from a management server and apply to the system.

RBFS Licensing allows you to access the full functionality of your RtBrick FullStack (RBFS) installation. Rtbrick provides a 28-day evaluation license on request. It is not allowed to be used in production. Use a permanent or subscription license that has been purchased through RtBrick Sales. If you want to extend the evaluation period and get additional licenses, contact RtBrick Support.

Without any license installed on your system, you can evaluate RBFS for 7 days. You need to get an evaluation license or purchase an actual license within 7 days to use the full functionality of RBFS.

To obtain RBFS licenses, get in touch with the Support team by email: support@rtbrick.com

You can install a license by using the RBFS CLI or via the RESTCONF API. You should get a license encrypted string from Rtbrick and configure the same via CLI.

To install a license, enter the following command:

The following example shows the running configuration.

You can install multiple licenses. Additional licenses can be installed even when you have existing license(s). The license with the maximum evaluation period will be prioritised over others. When you have multiple evaluation licenses installed, the one that expires later takes higher priority compared to the other licenses.

After verifying the validity of the license, the license file will be installed at the following location:

To delete a license, enter the following command:

When a license expires, you will not be able see the operational state of the system via CLI or BDS API.

©Copyright 2024 RtBrick, Inc. All rights reserved. The information contained herein is subject to change without notice. The trademarks, logos and service marks ("Marks") displayed in this documentation are the property of RtBrick in the United States and other countries. Use of the Marks are subject to RtBrick’s Term of Use Policy, available at https://www.rtbrick.com/privacy. Use of marks belonging to other parties is for informational purposes only.