RBFS and Tools Installation

Introduction

RtBrick software is delivered via different means: RBFS (RtBrick Full Stack) software is delivered as custom RtBrick 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 be used on 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 to be used on supported Ubuntu Linux distribution (currently the only supported Ubuntu release is 18.04 LTS Bionic Beaver). We usually refer to this category of software as RtBrick Tools. The software delivered as Debian packages is composed of a set of CLI tools and/or daemons meant to facilitate working with RBFS containers and the RBFS API.

Debian package repositories containing the packages are published on https://releases.rtbrick.com/ and updated when new package versions are available.

Managed Software Download

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).

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

Step 1: Customer must generate a client certificate

To help (facilitate) this step RtBrick provides the rtb-apt tools. For more information, see the section The RtBrick APT tool.

Step 2: Customer must send a client certificate to RtBrick
Step 3: RtBrick will approve and trust client’s certificate
Step 4: Customer can now use usual rtb-apt, apt, rtb-image tools to download RtBrick software
rtb-image must be at least version 1.3.0 to correctly work with managed downloads.

The RtBrick APT tool

The RtBrick APT tool is a statically compiled Linux 64bit executable, currently verified on Ubuntu 18.04. It is provided through a direct download link.

Installing RtBrick APT Tool

Before you install the RtBrick APT Tool, ensure you have installed the following software:

  • GNU Privacy Guard (GPG), which is used by APT to validate repositories. To install GPG, enter the following command:

admin@rtbrick:~$ sudo apt install gnupg

  • HTTPS for APT, which is used by APT to access repositories via HTTPS

admin@rtbrick:~$ sudo apt install apt-transport-https

The example below shows the URL of the RtBrick APT tool package.

admin@rtbrick:~$ curl -o /tmp/rtb-apt https://releases.rtbrick.com/_/dl/sw/rtb-
apt/latest/linux_amd64/rtb-apt \

&& sudo mv /tmp/rtb-apt /usr/local/bin/ \
&& sudo chown root:root /usr/local/bin/rtb-apt \
&& sudo chmod ugo+x /usr/local/bin/rtb-apt

Generating a Certificate by Using the RtBrick APT tool

The example below shows how to generate a certificate by using the RtBrick APT tool.

admin@rtbrick:~$ sudo rtb-apt auth generate
A new self-signed TLS client certificate has been generated for this system:

Subject: CN=admin@rtbrick,OU=rtb-apt
Valid until: 2022-02-23 13:52:24 +0000 UTC
<...>

Please send the certificate in the PEM encoded format below to your RtBrick contact or to
support@rtbrick.com:

-----BEGIN CERTIFICATE-----
MIIGETCCA/mgAwIBAgIQURwHovZ71kn/4DtJa+MF6jANBgkqhkiG9w0BAQsFADAs
MRAwDgYDVQQLEwdydGItYXB0MRgwFgYDVQQDDA9tYXJ0aW5AdmJveC12bTEwHhcN
MjEwMjI0MTM1MjI0WhcNMjIwMjIzMTM1MjI0WjAsMRAwDgYDVQQLEwdydGItYXB0
MRgwFgYDVQQDDA9tYXJ0aW5AdmJveC12bTEwggIiMA0GCSqGSIb3DQEBAQUAA4IC
DwAwggIKAoICAQC2V7PxE6ZjEkSKkmQClS4Wo/1kNsbIJpYae4wRIPp6NHD3EibW
KIJgNt7bIDIoFsDtL02CjgyxCPPU87d/1jBPGBD+zp+QNOAyHtcYvKgURj63EYe7
gpQrYHXTYdMd+gxbHgjSV/Kj6iSubL6C2Xnu5GYfcgRoLhPtEJ5dYscyu2LW3uW4
<...>
-----END CERTIFICATE-----

Identifying and Adding Package Repositories

Find available repositories

The example below shows how to find the available repositories.

admin@rtbrick:~$ rtb-apt repo list
Group Repository Distribution Release Active Restricted
releases/latest rtbrick-tools ubuntu bionic No No
releases/latest rtbrick-rbfs ubuntu bionic No No
releases/latest rtbrick-onl debian stretch No No

Activate repository

The example below shows how to activate the repositories.

admin@rtbrick:~$ sudo rtb-apt repo activate releases/latest/rtbrick-tools

The activated repositories are added to /etc/apt/sources.list.d/rtbrick.list.

Verify active repositories

The example below shows how to verify the active repositories.

admin@rtbrick:~$ rtb-apt repo list
Group Repository Distribution Release Active Restricted
releases/latest rtbrick-tools ubuntu bionic Yes No
releases/latest rtbrick-rbfs ubuntu bionic No No
releases/latest rtbrick-onl debian stretch No No

Verifying Authentication for Package Repositories

  • Firstly, your certificate needs to be added to the trusted list by RtBrick

  • Verify access to RtBrick package repositories

    • If your certificate is accepted, you can use APT to download packages

admin@rtbrick:~$ sudo rtb-apt auth check
Repository: releases/latest/rtbrick-tools ... restricted ... TLS client certificate accepted

Installing RtBrick Image Tool

The RtBrick image tool (rtb-image) uses the certificate generated by APT tool. It requires version 1.3.0. It can be installed from the (restricted) the tools repository.

You need to activate the tools repository by entering the following command:

admin@rtbrick:~$ sudo rtb-apt repo activate releases/latest/rtbrick-tools

Install or upgrade RtB image tool

To install the RtB image tool, enter the following command:

admin@rtbrick:~$ sudo apt update
admin@rtbrick:~$ sudo apt install rtbrick-imgstore

Verifying Authentication for Image Stores

View available image stores

The example below shows how to view the available image stores.

admin@rtbrick:~$ sudo rtb-image stores list
Index    UUID                                    Name         RemoteURL                                        Active    Restricted
0        af73c0a6-40e7-4775-b74b-aadafeabe86d    latest       https://releases.rtbrick.com/_/images/latest     Yes       No
1        c4c896b0-52c5-4343-8a21-e2ca3ea440f1    resources    https://releases.rtbrick.com/_/resources         No        No
2                                                22.5.1       https://releases.rtbrick.com/_/images/22.5.1     No        No
3                                                22.6.1       https://releases.rtbrick.com/_/images/22.6.1     No        No
4                                                22.7.1       https://releases.rtbrick.com/_/images/22.7.1     No        No
5                                                22.8.1       https://releases.rtbrick.com/_/images/22.8.1     No        No
<...>

Activate (restricted) image store

The example below shows how to activate (restricted) image store.

admin@rtbrick:~$ sudo rtb-image stores activate 1

Verify access to image stores

If your certificate is accepted, you can use rtb-image to download images.

The example below shows how to verify the access to the image stores.

admin@rtbrick:~$ sudo rtb-image auth check
Image store: latest (af73c0a6-40e7-4775-b74b-aadafeabe86d) ... restricted ... TLS client certificate accepted

RtBrick Tools and Packages

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.

rtbrick-toolkit

Version 23.6.1

The rtbrick-toolkit package has been updated to version 23.6.1 to match the corresponding RBFS release and has been updated to depend on the following RtBrick tools packages with these exact versions:

  • rtbrick-imgstore 3.2.0

  • rtbrick-ansible 5.1.3

  • rtbrick-apigwd 0.11.0

  • rtbrick-ctrld 0.20.0

  • rtbrick-lxcd 0.0.8

  • rtbrick-robot-infrastructure 3.0.0

  • rtbrick-fabric-ztp 2.0.1

rtbrick-ansible version 5.0.1 is compatible with the new RBFS RESTCONF hierarchy that was introduced with RBFS version 23.4.1. Therefore, rtbrick-ansible version 5.0.1 is backward-incompatible and will not work correctly with RBFS versions older than 23.4.1.

Understanding RBFS Release Versioning

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' can be 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 2 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.).

RtBrick Tools Installation

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

The following commands and outputs are validated only for the Ubuntu 18.04 LTS Bionic Beaver release.
Step 1: Removing any existing RtBrick tools Debian packages

Some of the RtBrick tools Debian packages have changed and have been upgraded several times. If some the RtBrick tools packages are already installed, it might be necessary to remove the currently installed versions:

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

Among other output, you will get the following:

The following packages will be REMOVED:

rtbrick-ansible rtbrick-imgstore rtbrick-lxc-tools

Step 2: Please use rtb-apt to configure debian package repositories
Step 3: Update the local apt package cache

We then have to update the local apt package cache: sudo apt update

Step 5: Install 3rd-party dependencies

Some RtBrick tools packages might have dependencies on 3rd-party software which cannot be delivered though the RtBrick package repositories.

Currently the rtbrick-ansible package depends on Ansible. For installing Ansible, you can use the official documentation that can be found at https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-on-ubuntu.

One very important dependency of rtbrick-ansible is Ansible itself. Make sure you have the latest version of Ansible installed, before trying to install rtbrick-ansible!
Step 6: Install a specific RtBrick tool package

For example, in order to install the rtbrick-ansible package, if the steps above have been completed successfully is it sufficient to run the following command:

sudo apt install rtbrick-ansible

RtBrick tools packages

rtbrick-toolkit

The rtbrick-toolkit is a meta package that can be used to install all the tools needed to work with RBFS images (container or ONL installer) and with the RBFS API in one command:

sudo apt install rtbrick-toolkit

The rtbrick-toolkit meta package depends and thus automatically installs the following packages:

  • rtbrick-imgstore

  • rtbrick-ansible

  • rtbrick-apigwd

  • rtbrick-ctrld

  • rtbrick-robot-infrastructure

If only part of the functionality is required each package can be installed individually.

rtbrick-ansible

To speed up the process of RBFS container bring up, the rtbrick-ansible package provides the rtb-ansible command which is an ansible based automation solution used to create and maintain topologies of RBFS containers and optionally to configure the RtBrick applications in each container.

The rtbrick-ansible package can be installed with the following command:

sudo apt install rtbrick-ansible

More information about rtb-ansible and how to use it is available in the RtBrick Automation Using Ansible manual.

rtbrick-imgstored

This package provides the rtb-image CLI utility which is RtBrick’s image store handling tool. An image store (imgstore) is a versioned, checksumed and cryptographically signed store of versioned files. It was developed and optimized with the primary goal of storing and distributing Linux OS and Linux container images however it can be used to store any kind of files.

An image store is for images what an apt repository is for Debian packages. It also has some similarities with a docker registry (not to be confused with a docker repository).

The rtb-image command is used for interacting with an image store accessible via HTTP(s), making a local cache of that image store that can later be used to start LXC containers running RBFS.

rtbrick@access-test:~$ sudo apt search rtbrick-imgstore
Sorting... Done
Full Text Search... Done
rtbrick-imgstore/bionic,now 2.1.1-xdaily.20220531062114+Cc35c1aa0-bionic amd64 [installed]
  RtBrick image store handling tool

rtbrick-imgstore-server/bionic 0.9.0-internal.20210615185257+Bdevelopment.C506acfa4-focal amd64
  RtBrick Image Store Upload Server

rtbrick@access-test:~$ sudo apt show rtbrick-imgstore
Package: rtbrick-imgstore
Version: 2.1.1-xdaily.20220531062114+Cc35c1aa0-bionic
Priority: extra
Section: rtbrick-tools
Maintainer: RtBrick Support <support@rtbrick.com>
Installed-Size: 29.4 MB
Provides: rtbrick-imgstore
Depends: liblxc-common, liblxc1, lxc, zstd
Replaces: rtbrick-imgstore
Download-Size: 11.1 MB
APT-Manual-Installed: yes
APT-Sources: https://pkg.rtbrick.net/_/latest/ubuntu/rtbrick-tools bionic/rtbrick-tools amd64 Packages
Description: RtBrick image store handling tool
 RtBrick package tracker UUID=89989764-69f8-4848-a066-8f8db2360253

N: There are 139 additional records. Use the '-a' switch to see them.

The tool (the binary) has in it embedded the GPG public key of support@rtbrick.com, identity which is used to sign all RtBrick images and the image store itself.

Common usage of rtb-image

rtb-image has enough versatility, but a few options are commonly used:

  • containers list - List all the LXC containers which are created on the local system.

  • show [<flags>] <UUID> - Show details of image identified by UUID. By default, this shows the image in the local cached copy of the store.

  • run --name=NAME [<flags>] <UUID> - Run an LXC container using the specified image. The container must not be already created.

  • list [<flags>] <UUID> - List all the images in the store. By default, this lists the images in the local cached copy of the store.

rtb-image list flags
Value Description

-o, --remote

List images directly from the remote store and not from the local cached copy.

-d, --detailed

List detailed information about images.

-f, --format=FORMAT

List only images with a specific format.

-r, --role=ROLE

List only images with a specific role. Currently, roles are spine, accessleaf, and consolidated-bng.

-p, --platform=PLATFORM

List only images for a specific platform.

-v, --ver-range=VER-RANGE

List only images versions that fall in the provided version range. See the syntax for version ranges at https://godoc.org/github.com/blang/semver#Range . The hardcoded strings 'latest' or 'newest' will always filter down to a single image, the one considered the newest according to the sorting rules for versions.

-l, --limit=LIMIT

Limit the list of returned images to the the l newest images.

An important part of rtb-image is that it is used to create a local cache of the remote RtBrick image repo. This is done using the rtb-image update command:

rtbrick@access-test:~$ sudo rtb-image update
Local image store cached copy updated to: Store: /var/cache/rtbrick/imagestores/847c6ecd-df58-462e-a447-38c620a12fe1 Version: 0.22.6360 ValidUntil: 2195-05-21 12:27:50.527696657 +0000 UTC

Then we can list the local copies:

rtbrick@access-test:~$ sudo rtb-image list

Store: /var/cache/rtbrick/imagestores/847c6ecd-df58-462e-a447-38c620a12fe1 Version: 0.22.6360 ValidUntil: 2195-05-21 12:27:50.527696657 +0000 UTC

UUID                                	Version                                      	Filename                                     	Format       	Role               	Platform	Cached
decbae82-6726-4816-92f7-ea0da4948c9b	22.6.0-g8daily.20220605220704+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	l2bsa              	qax     	false
d9bad050-d03e-4c65-beb4-0dbcefbb155f	22.6.0-g8daily.20220605220704+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	consolidated-bng   	qax     	false
f26833f0-c431-411e-a1b2-a8a0af3467e8	22.6.0-g8daily.20220605220700+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	accessleaf         	qmx     	false
fa129e98-c2a3-487d-a5ac-6c10a7c9b67e	22.6.0-g8daily.20220605220700+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	accessleaf         	q2c     	false
fa52399e-a2d8-48f0-8ad0-5b17b69b826d	22.6.0-g8daily.20220605220700+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	spine              	qmx     	false
4f2677b7-da1f-4afb-8195-391144701983	22.6.0-g8daily.20220605220700+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	spine              	q2c     	false
4a347812-5ae3-496b-a07f-658ce1e4f8de	22.6.0-g8daily.20220605215030+Bmaster.C8dd...	rbfs-cont/rbfs-l2bsa-qax-22.6.0-g8daily.20...	lxd          	l2bsa              	qax     	false
2346b546-9066-45bc-b104-ea9dbcfe21d5	22.6.0-g8daily.20220605215029+Bmaster.C8dd...	rbfs-cont/rbfs-consolidated-bng-qax-22.6.0...	lxd          	consolidated-bng   	qax     	false
90668764-e1d7-4abb-8a35-de44e89e2cf4	22.6.0-g8daily.20220605215028+Bmaster.C8dd...	rbfs-cont/rbfs-spine-q2c-22.6.0-g8daily.20...	lxd          	spine              	q2c     	false
2b4a4e88-271b-49ef-8622-df3d6b4ec044	22.6.0-g8daily.20220605215028+Bmaster.C8dd...	rbfs-cont/rbfs-accessleaf-q2c-22.6.0-g8dai...	lxd          	accessleaf         	q2c     	false
0f2b85ec-7642-4ac7-8f2f-09969dbd7600	22.6.0-g8daily.20220605215028+Bmaster.C8dd...	rbfs-cont/rbfs-spine-qmx-22.6.0-g8daily.20...	lxd          	spine              	qmx     	false
bb8c20ad-4015-43cf-aee1-a7531956cb13	22.6.0-g8daily.20220605215028+Bmaster.C8dd...	rbfs-cont/rbfs-accessleaf-qmx-22.6.0-g8dai...	lxd          	accessleaf         	qmx     	false
72b4e586-b231-4fb8-b727-8d57bcdba6ad	22.6.0-g8daily.20220605215021+Bmaster.C8dd...	rbfs-cont/rbfs-consolidated-bng-virtual-22...	lxd          	consolidated-bng   	virtual 	false
8e917833-f028-4d92-b748-2ecc0873cbc2	22.6.0-g8daily.20220605215021+Bmaster.C8dd...	rbfs-cont/rbfs-accessleaf-virtual-22.6.0-g...	lxd          	accessleaf         	virtual 	false
95ba662b-e45a-4503-aef5-1056525a0814	22.6.0-g8daily.20220605215021+Bmaster.C8dd...	rbfs-cont/rbfs-l2bsa-virtual-22.6.0-g8dail...	lxd          	l2bsa              	virtual 	false
067b4fc0-e633-4197-bd53-8467bf8a1af6	22.6.0-g8daily.20220605215021+Bmaster.C8dd...	rbfs-cont/rbfs-spine-virtual-22.6.0-g8dail...	lxd          	spine              	virtual 	false
fd52536e-bd16-421d-a883-da263768aeb6	22.6.0-g8daily.20220605102529+Bmaster.C2f0...	rtbrick-onl-base/rtbrick-onl-base-22.6.0-g...	onl-installer	rtbrick-onl-base   	hw      	false
97110f63-8d57-420a-8d6a-a5f5f89d3d5b	22.6.0-g8daily.20220605102529+Bmaster.C8dd...	rtbrick/ubuntu-bionic-22.6.0-g8daily.20220...	lxd          	rtbrick-ubuntu-base	all     	false
11193467-3253-4eba-bed9-cb145d6a6ce4	22.6.0-g8daily.20220605100017+Bmaster.Cd2a...	opennetworklinux/ONL-HEAD_ONL-OS10_2022-06...	onl-installer	onl-base           	hw      	false
2a8b3a59-7db0-40a2-828b-4c2ee4b8ee9a	22.6.0-g8daily.20220604220631+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	consolidated-bng   	qax     	false
cde5779e-21c5-460b-976e-f5ee2cce8454	22.6.0-g8daily.20220604220631+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	l2bsa              	qax     	false
8a311a17-5d66-47e5-8b70-85b8b1777371	22.6.0-g8daily.20220604220627+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	spine              	q2c     	false
168de847-95d3-4812-b198-64707749dd57	22.6.0-g8daily.20220604220626+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	accessleaf         	qmx     	false
48d921d4-8882-4df1-9455-041d979be419	22.6.0-g8daily.20220604220626+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	accessleaf         	q2c     	false
5175525c-4fdc-445a-93ff-75cd5ad4f733	22.6.0-g8daily.20220604220625+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	spine              	qmx     	false
1d0f73fd-8888-4c92-86e1-b5405d085ec8	22.6.0-g8daily.20220604214821+Bmaster.C8dd...	rbfs-cont/rbfs-l2bsa-qax-22.6.0-g8daily.20...	lxd          	l2bsa              	qax     	false
1eb22e3e-9ef6-44a4-86ed-ffbd11cdc224	22.6.0-g8daily.20220604214820+Bmaster.C8dd...	rbfs-cont/rbfs-consolidated-bng-qax-22.6.0...	lxd          	consolidated-bng   	qax     	false
4777df7b-132e-4294-8e38-df2de3a8ba7b	22.6.0-g8daily.20220604214816+Bmaster.C8dd...	rbfs-cont/rbfs-accessleaf-q2c-22.6.0-g8dai...	lxd          	accessleaf         	q2c     	false
72d910ba-25d4-4726-a543-3d349630763d	22.6.0-g8daily.20220604214816+Bmaster.C8dd...	rbfs-cont/rbfs-accessleaf-qmx-22.6.0-g8dai...	lxd          	accessleaf         	qmx     	false
0c3186cc-ce6e-4747-99da-24cb18625b62	22.6.0-g8daily.20220604214816+Bmaster.C8dd...	rbfs-cont/rbfs-spine-q2c-22.6.0-g8daily.20...	lxd          	spine              	q2c     	false
c91a0af4-16e5-4f25-b515-1200a85ead42	22.6.0-g8daily.20220604214815+Bmaster.C8dd...	rbfs-cont/rbfs-spine-qmx-22.6.0-g8daily.20...	lxd          	spine              	qmx     	false
e44a2be2-ebff-423b-a3fb-4fcda2542ef5	22.6.0-g8daily.20220604214812+Bmaster.C8dd...	rbfs-cont/rbfs-consolidated-bng-virtual-22...	lxd          	consolidated-bng   	virtual 	false
2e585361-579f-4001-92d4-736aa79e24f3	22.6.0-g8daily.20220604214811+Bmaster.C8dd...	rbfs-cont/rbfs-l2bsa-virtual-22.6.0-g8dail...	lxd          	l2bsa              	virtual 	false
aec6df05-8883-47b2-98fe-83c2030d0391	22.6.0-g8daily.20220604214811+Bmaster.C8dd...	rbfs-cont/rbfs-spine-virtual-22.6.0-g8dail...	lxd          	spine              	virtual 	false
952bfaa0-b597-48a4-9006-d4d006509bcc	22.6.0-g8daily.20220604214810+Bmaster.C8dd...	rbfs-cont/rbfs-accessleaf-virtual-22.6.0-g...	lxd          	accessleaf         	virtual 	false
9cb9842e-2bb2-46dc-a43c-dc1b1f3acd52	22.6.0-g8daily.20220603220408+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	consolidated-bng   	qax     	false
32623f70-3ffb-43e4-ba3b-1d351d8bf71b	22.6.0-g8daily.20220603220408+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	l2bsa              	qax     	false
f65ae5fc-aa3b-4ed1-8d4b-d0559ccba9eb	22.6.0-g8daily.20220603220404+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	accessleaf         	qmx     	false
3205637e-aa2a-4f5e-95fa-05ef36c1ae7d	22.6.0-g8daily.20220603220403+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	spine              	q2c     	false
c6e2589f-df88-414e-b163-721a8336bcef	22.6.0-g8daily.20220603220403+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	spine              	qmx     	false

rtbrick-fabric-ztp

This package provides an implementation of a Zero-Touch Provisioning (ZTP) server. This is needed for automatic provisioning of switches newly installed in a network, where the ZTP-server provides installation/upgrade images for the switches.

The rtbrick-fabric-ztp package can be installed with the following command:

sudo apt install rtbrick-fabric-ztp

After installation, the server is running as a systemd-daemon by default on port 80 and taking ZTP configuration files from the location /var/rtbrick/ztp/configs/.

More information about the ZTP process and configuration can be found at the following link:
https://documents.rtbrick.com/current/ztp/ztp_guide_online.html

Image formats and ONL image installation for supported hardware

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

  • format: This is the file format of in which the image is packaged and archived.

  • role: The role inside a network of the device which will be running the image.

  • platform: Identifies the hardware platform or virtualized environment in which the image can run.

RtBrick images mean to be used as containers in a virtualized environment will have format == lxd and platform == virtual.

RtBrick images mean to be installed on supported whitebox switch hardware devices will have format == onl-installer and platform set accordingly to the specific switching hardware.

You can see this using rtb-image list command and looking for the Format column.

ONL images

ONL images are generally installed using a Zero Touch Provisioning (ZTP) server. The [Installation] section applies for both virtual and hardware installations, with the difference that, when having a physical deployment (One with a ZTP server and switched running ONL images) we can install just the rtbrick-imgstore package on the ZTP server, since it doesn’t have Ansible as dependency (Ansible not being a part of the default Ubuntu repositories), and because generally you will not have containers running on the ZTP server itself.

A typical ONL image download will look as in the following snippet:

rtbrick@access-test:~$ sudo rtb-image update
Local image store cached copy updated to: Store: /var/cache/rtbrick/imagestores/847c6ecd-df58-462e-a447-38c620a12fe1 Version: 0.22.6360 ValidUntil: 2195-05-21 12:27:50.527696657 +0000 UTC

rtbrick@access-test:~$ sudo rtb-image list --format onl-installer --platform qmx --role spine --ver-range latest

Store: /var/cache/rtbrick/imagestores/847c6ecd-df58-462e-a447-38c620a12fe1 Version: 0.22.6360 ValidUntil: 2195-05-21 12:27:50.527696657 +0000 UTC

UUID                                	Version                                      	Filename                                     	Format       	Role 	Platform	Cached
fa52399e-a2d8-48f0-8ad0-5b17b69b826d	22.6.0-g8daily.20220605220700+Bmaster.C2f0...	rtbrick-onl-installer/rtbrick-onl-installe...	onl-installer	spine	qmx     	false

rtbrick@access-test:~$ sudo rtb-image pull fa52399e-a2d8-48f0-8ad0-5b17b69b826d
rtbrick-onl-installer-spine-qmx-22.6.0-g8daily.20220605220700+Bmaster.C2f0eae65.d.sha512 244 B / 244 B [===================================================================] 100.00% 0s
rtbrick-onl-installer-spine-qmx-22.6.0-g8daily.20220605220700+Bmaster.C2f0eae65.d.asc 833 B / 833 B [======================================================================] 100.00% 0s
rtbrick-onl-installer-spine-qmx-22.6.0-g8daily.20220605220700+Bmaster.C2f0eae65.d 1.15 GiB / 1.15 GiB [====================================================================] 100.00% 5s
rtbrick-onl-installer-spine-qmx-22.6.0-g8daily.20220605220700+Bmaster.C2f0eae65.d: decompressing 100 B / 100 B [===========================================================] 100.00% 0s

rtbrick@access-test:~$ sudo rtb-image show fa52399e-a2d8-48f0-8ad0-5b17b69b826d

Store: /var/cache/rtbrick/imagestores/847c6ecd-df58-462e-a447-38c620a12fe1 Version: 0.22.6360 ValidUntil: 2195-05-21 12:27:50.527696657 +0000 UTC

UUID:             	fa52399e-a2d8-48f0-8ad0-5b17b69b826d
Version:          	22.6.0-g8daily.20220605220700+Bmaster.C2f0eae65
Creation Date:    	2022-06-06 03:37:00 +0530 IST (7 hours ago)
Role:             	spine
Platform:         	qmx
Format:           	onl-installer
Architecture:     	amd64
Filename:         	rtbrick-onl-installer/rtbrick-onl-installer-spine-qmx-22.6.0-g8daily.20220605220700+Bmaster.C2f0eae65.d
FullPath/URL:     	/var/cache/rtbrick/imagestores/847c6ecd-df58-462e-a447-38c620a12fe1/rtbrick-onl-installer/rtbrick-onl-installer-spine-qmx-22.6.0-g8daily.20220605220700+Bmaster.C2f0eae65.d
SHA512:           	9a6b989edacf8daedc656dce310eb4ad680dc3cd5afd16a9c1783bb57ac78c97b4cc2d30fd0ac91edd2ef7a86c7d6aea6441ef2ef0fbd16cd1f682f21601ed64
Base Image:       	fd52536e-bd16-421d-a883-da263768aeb6
Embedded Packages:	18
Embedded Images:  	1
Cached:           	true
ExtractedPath:

In a design where the download of the image happens on a different server than the ZTP used for the actual installation, you can install the rtbrick-imgstore package, and move by some means ( rsync, for example) the images from var/cache/rtbrick/imagestore/ of that internet-connected to the ZTP server.

The rtb-ssh CLI command

rtb-ssh is a script meant to ease connecting into an already running container. It was previously called rssh , and it was renamed, as it was causing confusion with Linux’s restricted shell rssh package which is available in the official Ubuntu apt package repositories.

Besides renaming only minor some 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 create 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 clear the environment before attaching, so no undesired environment variables leak into the container. The variable container=lxc will be 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, etc.

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

Manual installation of Images

The Open Network Install Environment (ONIE is an open-source project within the Open Computer Project that provides an installation environment for bare-metal networking switches. ONIE is used to install different NOSes (network operating systems) on a target device.

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

Prerequisites

  • Open Network Install Environment (ONIE) should be installed on the switch by the vendor of the switch. If it’s unavailable with the switch, contact the switch vendor.

  • The switch management interface has been provisioned with an IP address either manually configured or through DHCP.

  • You need to set up necessary infrastructure to download RtBrick ONL installer images in your environment. Refer to the RtBrick Tools Installation Guide.

  • You need to set up a HTTP server that will make available the downloaded images for ONIE to use. For more information information, see the following URL:
    https://opencomputeproject.github.io/onie/user-guide/index.html#installing-over-the-network

Installation Procedure

To install the ONL image, perform the following steps:

On a fresh box, ONL prompt will not be available so skip to ONIE prompt section.

ONL prompt section:

Option 1: Manually select ONIE boot mode

  1. Connect to console port

  2. Reboot switch

root@bl1-pod1:~# reboot

  1. Select "ONIE" from first selection menu

  2. Select "ONIE: Install OS" from next selection menu

onie

  1. Install RBFS ONL image

Option 2: Preselect ONIE boot mode

  1. Connect to console port

  2. Select ONIE boot mode

root@onl>ufi03.q2c.u15.r4.nbg.rtbrick.net:~ # onl-onie-boot-mode --help
usage: onl-onie-boot-mode [-h] [--onie-only]
                          {install,rescue,uninstall,update,embed,diag,none}

positional arguments:
  {install,rescue,uninstall,update,embed,diag,none}

optional arguments:
  -h, --help            show this help message and exit
  --onie-only           Do not set ONIE boot menu option.
root@onl>ufi03.q2c.u15.r4.nbg.rtbrick.net:~ #

root@onl>ufi03.q2c.u15.r4.nbg.rtbrick.net:~ # onl-onie-boot-mode install
The system will boot into ONIE install mode at the next restart.
root@onl>ufi03.q2c.u15.r4.nbg.rtbrick.net:~ #

  1. Reboot switch

root@onl>ufi03.q2c.u15.r4.nbg.rtbrick.net:~ # reboot

ONIE prompt section:

You need to update the URL of the ONL installer image location according to your own specific HTTP server configuration.

ONIE:/ # onie-discovery-stop
NOTICE: The 'onie-discovery-stop' command is deprecated and will be removed in 2019.02.
NOTICE: Use 'onie-stop' instead.
discover: installer mode detected.
Stopping: discover... done.

ONIE:/ # onie-nos-install http://server.example.net/_/images/latest/rtbrick-onl-ins
taller/rtbrick-onl-installer-spine-q2c-21.9.1.d

discover: installer mode detected.
Stopping: discover... done.

Info: Attempting http://server.example.net/_/images/latest/rtbrick-onl-installer/rtbrick-onl-installer-spine-q2c-21.9.1.d ...

Connecting to server.example.net (198.51.100.125)
installer 100% |*******************************| 1176M 0:00:00 ETA

ONIE: Executing installer: http://server.example.net/_/images/latest/rtbrick-onl-installer/rtbrick-onl-installer-spine-q2c-21.9.1.d