RBFS Image Download

The RtBrick image 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 mutual TLS authentication with TLS client certificates (TLS client certificates can be self-signed).

The diagram below provides an overview of the RBFS software download process.

software download overview

The process of downloading software involves the following tasks:

1. Generating a Client Certificate

RtBrick provides the rtb-apt tool to generate a client certificate. This section contains the following topics:

1.1. About the RtBrick APT Tool (rtb-apt)

The rtb-apt tool is an APT utility application that provides an easier way for managing the system configuration of RtBrick package repositories 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 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.

1.2. Installing the rtb-apt Tool

This section contains the following topics:

1.2.1. Prerequisites to Install the rtb-apt Tool

Before you install rtb-apt, ensure that you have installed the following software:

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

sudo apt install gnupg
  • HTTPS support for apt is required to access the package repositories via HTTPS. To do this, enter the following command:

sudo apt install apt-transport-https ca-certificates

1.2.2. Downloading and Installing the rtb-apt Tool

The following example shows how to download and install the rtb-apt tool. It shows the URL where the latest version of the rtb-apt tool is available for download:

❯ 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 0755 /usr/local/bin/rtb-apt

1.2.3. Verifying the Version of the rtb-apt Tool

The following example shows the rtb-apt tool version. The rtb-apt version 2.1.2 or later is required.

❯ rtb-apt --version
2.1.2

1.3. Generating a TLS Client Certificate

The following example shows how to generate a TLS client certificate using the rtb-apt tool.

❯ sudo rtb-apt auth generate
A new self-signed TLS client certificate has been generated for this system:

Subject:     CN=bb59a25d-6b38-4f3c-81e0-065e525c8335,OU=rtb-apt
Valid until: 2024-09-06 10:30:26 +0000 UTC

The following additional auto-generated information is included in the certificate and can be used to uniquely identify this system:

DNS names:       [hostname.example.net]
Email addresses: [root@hostname.example.net user@hostname.example.net]
< ......................................... >

If you already have a working account on https://portal.rtbrick.com then you can use the Self-Service section to upload this certificate. If you DO NOT yet have an account on https://portal.rtbrick.com, send the certificate to your RtBrick support contact:


-----BEGIN CERTIFICATE-----
MIIHHzCCBYegAwIBAgIRAJcI5pqSK9O+g6yJGB15i7YwDQYJKoZIhvcNAQELBQAw
QTEQMA4GA1UECxMHcnRiLWFwdDEtMCsGA1UEAxMkYmI1OWEyNWQtNmIzOC00ZjNj
< ......................................... >
NuLIKfmwrcyXmzAOe1bRtlJrRw0zofxX4rFcMmJReNqOV0obP5r7TCtnWtAqkFx/
7JJa
-----END CERTIFICATE-----

After generating the TLS Client Certificate, you need to upload it to the the Certificates section on https://portal.rtbrick.com. For details about uploading a certificate, see section Upload the Certificate to the Self-Service Portal below.

2. Uploading the Client Certificate to the Self-Service Portal

If your domain is registered with https://portal.rtbrick.com, you will be able to log into your account. If not, reach out to your sales/partner contact to initially have your domain registered with the portal.

To upload a new client certificate, perform the following steps:

  1. Log in to Self-Service Portal.

certificate list
  1. Click Certificates on the left navigation panel. The Certificates list page appears. The organization’s certificate list shows all certificates of that particular organization.

The filter options allows filtering certificates by their distinguished name or lifecycle status.

  1. Click the Upload certificate button in the organization’s certificate list view to upload a new client certificate.

Client cert upload form
  1. Copy the certificate content in PEM format into the text area. The description field is optional, but it can be used to provide additional information about the certificate.

  1. Click the Upload certificate button to upload a new certificate.

3. Obtaining Approval and verification of the Client Certificate

  1. RtBrick reviews and approves the client’s certificate that is uploaded on the Self-Service portal.

  2. After RtBrick approves the certificate, verify it by entering the command "sudo rtb-apt auth check".

❯ sudo rtb-apt auth check
Repository: releases/latest/rtbrick-tools ... restricted ... TLS client certificate accepted

If the client certificate is not accepted by RtBrick, the following message will appear. Please contact the customer support team.

❯ sudo rtb-apt auth check
Repository: releases/latest/rtbrick-tools ... restricted ... TLS client certificate NOT accepted

4. Identifying and Activating the Image Repository

You can install additional RtBrick Tools that help simplifying tasks related to debian package repositories. For details see Installing the rtb-image Tool and Verifying Access to Image Stores

This section contains the following topics:

4.1. Finding the Image Repositories

To find the available repositories, enter the "sudo rtb-apt repo list" command.

The following example shows how to find the available repositories:

❯ sudo rtb-apt repo list
Group           	Repository   	Distribution	Release	Active	Restricted
releases/latest 	rtbrick-tools	ubuntu      	jammy  	No    	No
< ......................................... >

4.2. Activating an Image Repository

To activate an image repository, enter the "sudo rtb-apt repo activate" command.

The following example shows how to activate the "releases/latest/rtbrick-tools" repository.

❯ sudo rtb-apt repo activate releases/latest/rtbrick-tools

rtb-apt activated repository is added to /etc/apt/sources.list.d/rtbrick.list so that the repository can then be used with commands such as apt update and apt install to install the RtBrick Debian tool packages.

❯ cat /etc/apt/sources.list.d/rtbrick.list
deb [arch=amd64 signed-by=/etc/rtbrick/RtBrick-Support.pubkey.asc] https://releases.rtbrick.com/_/latest/ubuntu/jammy/rtbrick-tools    jammy    rtbrick-tools

4.3. Verifying the Active Repositories

To verify the active repositories, use the "sudo rtb-apt repo list" command. For example in the below output releases/latest repository is active because its status is set to YES.

❯ sudo rtb-apt repo list
Group          	Repository   	Distribution	Release	Active	Restricted
releases/latest	rtbrick-tools	ubuntu      	jammy  	Yes   	Yes
< ..................................... >

5. Installing the rtb-image Tool and Verifying Access to Image Stores

Once the TLS client certificate for the current system is trusted by RtBrick and once RtBrick package repositories have been activated with rtb-apt, the apt commands can be used to install the RtBrick software contained in those package repositories.

rtb-image version 3.11.0 or later is required to correctly work with managed downloads.

This section contains the following topics:

5.1. Installing the rtbrick-imgstore Package

If you have any existing RtBrick tools packages, it is essential to upgrade to the latest version because some of the RtBrick tools Debian packages have changed and have been upgraded several times. You can remove the exisiting RtBrick tools package using the below command:
apt list --installed | egrep -i rtbrick-imgstore | awk -F '/' '{print $1;}' | xargs sudo apt remove -y

The following shows the installation of the rtbrick-imgstore package which provides the rtb-image CLI tool.

❯ sudo apt update
Hit:1 https://releases.rtbrick.com/_/latest/ubuntu/jammy/rtbrick-tools jammy InRelease
Hit:3 http://archive.ubuntu.com/ubuntu jammy InRelease
Get:4 http://archive.ubuntu.com/ubuntu jammy-updates InRelease [119 kB]
Get:7 http://archive.ubuntu.com/ubuntu jammy-backports InRelease [109 kB]
Get:8 http://archive.ubuntu.com/ubuntu jammy-security InRelease [110 kB]
Get:9 http://archive.ubuntu.com/ubuntu jammy-updates/main amd64 Packages [970 kB]
Get:10 http://archive.ubuntu.com/ubuntu jammy-updates/universe amd64 Packages [979 kB]
< ......................................... >
❯ sudo apt install rtbrick-imgstore
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following NEW packages will be installed:
  rtbrick-imgstore
0 upgraded, 1 newly installed, 0 to remove and 46 not upgraded.
Need to get 7,731 kB of archives.
After this operation, 26.3 MB of additional disk space will be used.
Get:1 https://releases.rtbrick.com/_/latest/ubuntu/jammy/rtbrick-tools jammy/rtbrick-tools amd64 rtbrick-imgstore amd64 3.3.0 [7,731 kB]
Fetched 7,731 kB in 0s (41.4 MB/s)
Selecting previously unselected package rtbrick-imgstore.
< ......................................... >

5.2. Verifying Access (Authentication) to Image Stores

The rtb-image command (CLI tool) provided by the rtbrick-imgstore package is used to interact with "image stores". The "image stores" are used for delivery of RBFS container images and RtBrick ONL installer images.

Similarly to package repositories some of the image stores are restricted meaning that they require the client application (rtb-image in this case) to authenticate with a TLS client certificate. rtb-image re-uses the TLS client certificate already generated by rtb-apt for the current system.

This section contains the following topics:

5.2.1. Viewing Available Image Stores

The following example shows how to view the available image stores:

❯ 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.2.2. Activating a Restricted Image Store

The following example shows how to activate a (possibly restricted) image store:

❯ sudo rtb-image stores activate 0

5.2.3. Verifying Access to Image Stores

If the TLS client certificate for the current system is already trusted by RtBrick, you can use rtb-image to download the images. Before downloading the image, you can verify the access to the image stores using the sudo rtb-image auth check command.

The following example shows how to verify the access to the image stores:

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

6. Downloading the ONL Image

Image stores contain the ONL installer images.

To download ONL installer images, perform the following steps:

6.1. Updating the Local Cached Copy of the Remote Image Store

Enter the following command to update the local cached copy of remote image store for RBFS container and ONL images.

❯ sudo rtb-image update
Local image store cached copy updated to: Store: /var/cache/rtbrick/imagestores/847c6ecd-df58-462e-a447-38c620a12fe1 Version: 2.4.60878 ValidUntil: 2180-12-25 11:58:44

6.2. Finding the ONL Image

To find the ONL image, enter the "sudo rtb-image list" command with the following options.

-f, --format=FORMAT          Filter images with a specific format. This must be an exact match of the image format attribute.
-r, --role=ROLE              Filter images with a specific role. This must be an exact match of the image role attribute.
-p, --platform=PLATFORM      Filter images for a specific platform. This must be an exact match of the image platform attribute.
-m, --model=MODEL            Filter images for a specific model. This must be an exact match of the image model attribute.
-v, --ver-range=VER-RANGE    Filter images with versions that fall in the provided version range. See the syntax for version ranges at

The following example shows how to find the ONL image details for UfiSpace S9510-28DC Consolidate-BNG image.

❯ sudo rtb-image list --format onl-installer --platform q2a --role consolidated-bng --ver-range latest --model s9510-28dc
Store: /var/cache/rtbrick/imagestores/847c6ecd-df58-462e-a447-38c620a12fe1 Version: 2.4.60878 ValidUntil: 2180-12-25 11:58:44
UUID                                  Version               Role                 Model          Platform  Format         Cached
db568345-a313-4abd-8c14-4970396d048f  24.8.1   consolidated-bng     s9510-28dc     q2a       onl-installer  false

6.3. Pulling the ONL Image

There are two options available for downloading the ONL image:

  • Option 1: Downloading the image to the current working directory

  • Option 2: Downloading the image to a specific directory

Option 1: Downloading the image to the current working directory

To download the ONL image, use the UUID (for example, 7f52060d-4af4-4ca7-8fe7-3619ee7f6bfb) of the ONL image in the "sudo rtb-image pull" command. Use the "--here" option to download the image to the current working directory.

$ sudo rtb-image pull --here 7f52060d-4af4-4ca7-8fe7-3619ee7f6bfb
rtbrick-onl-installer-accessleaf-q2c-s9600-102xc-24.9.1-candidate.16.d.sha512 233 B / 233 B [==============================================================================] 100.00% 0s
rtbrick-onl-installer-accessleaf-q2c-s9600-102xc-24.9.1-candidate.16.d.asc 833 B / 833 B [=================================================================================] 100.00% 0s
rtbrick-onl-installer-accessleaf-q2c-s9600-102xc-24.9.1-candidate.16.d 1.17 GiB / 1.17 GiB [==============================================================================] 100.00% 10s
rtbrick-onl-installer-accessleaf-q2c-s9600-102xc-24.9.1-candidate.16.d: decompressing 100 B / 100 B [======================================================================] 100.00% 0s
7f52060d-4af4-4ca7-8fe7-3619ee7f6bfb downloaded as /home/rtbuser/playground

The Image will be downloaded to the current working directory under the rtbrick-onl-installer directory as shown below:

$ ls -al
total 36
drwxrwxr-x  6 rtbuser rtbuser 4096 Jan  9 05:18 .
drwxr-xr-x 16 rtbuser rtbuser 4096 Jan  9 05:17 ..
drwxr-xr-x  2 rtbuser rtbuser 4096 Jan  9 05:18 rtbrick-onl-installer

$ cd rtbrick-onl-installer/

$ ls -al
total 1227848
drwxr-xr-x 2 rtbuser rtbuser       4096 Jan  9 05:18 .
drwxrwxr-x 6 rtbuser rtbuser       4096 Jan  9 05:18 ..
-rw-r--r-- 1 rtbuser rtbuser 1257294496 Jan  9 05:18 rtbrick-onl-installer-accessleaf-q2c-s9600-102xc-24.9.1-candidate.16.d
-rw-r--r-- 1 rtbuser rtbuser        833 Jan  9 05:18 rtbrick-onl-installer-accessleaf-q2c-s9600-102xc-24.9.1-candidate.16.d.asc
-rw-r--r-- 1 rtbuser rtbuser        233 Jan  9 05:18 rtbrick-onl-installer-accessleaf-q2c-s9600-102xc-24.9.1-candidate.16.d.sha512

Option 2: Downloading the image to a specific directory

Another method to save the image to a specific directory is shown below:

$ sudo rtb-image pull --dst=/home/supervisor 7f52060d-4af4-4ca7-8fe7-3619ee7f6bfb
rtbrick-onl-installer-accessleaf-q2c-s9600-102xc-24.9.1-candidate.16.d.sha512 233 B / 233 B [==============================================================================] 100.00% 0s
rtbrick-onl-installer-accessleaf-q2c-s9600-102xc-24.9.1-candidate.16.d.asc 833 B / 833 B [=================================================================================] 100.00% 0s
rtbrick-onl-installer-accessleaf-q2c-s9600-102xc-24.9.1-candidate.16.d 1.17 GiB / 1.17 GiB [==============================================================================] 100.00% 11s
rtbrick-onl-installer-accessleaf-q2c-s9600-102xc-24.9.1-candidate.16.d: decompressing 100 B / 100 B [======================================================================] 100.00% 0s
7f52060d-4af4-4ca7-8fe7-3619ee7f6bfb downloaded as /home/supervisor

$ cd home/supervisor

$ ls -al
total 36
drwxrwxr-x  6 rtbuser rtbuser 4096 Jan  9 05:18 .
drwxr-xr-x 16 rtbuser rtbuser 4096 Jan  9 05:17 ..
drwxr-xr-x  2 rtbuser rtbuser 4096 Jan  9 05:18 rtbrick-onl-installer

$ cd rtbrick-onl-installer/

$ ls -al
total 1227848
drwxr-xr-x 2 rtbuser rtbuser       4096 Jan  9 05:18 .
drwxrwxr-x 6 rtbuser rtbuser       4096 Jan  9 05:18 ..
-rw-r--r-- 1 rtbuser rtbuser 1257294496 Jan  9 05:18 rtbrick-onl-installer-accessleaf-q2c-s9600-102xc-24.9.1-candidate.16.d
-rw-r--r-- 1 rtbuser rtbuser        833 Jan  9 05:18 rtbrick-onl-installer-accessleaf-q2c-s9600-102xc-24.9.1-candidate.16.d.asc
-rw-r--r-- 1 rtbuser rtbuser        233 Jan  9 05:18 rtbrick-onl-installer-accessleaf-q2c-s9600-102xc-24.9.1-candidate.16.d.sha512

6.4. Displaying the Location of the Downloaded Image

The details of the downloaded image can be viewed using the following command:

❯ sudo rtb-image show 7f52060d-4af4-4ca7-8fe7-3619ee7f6bfb
Store: /var/cache/rtbrick/imagestores/847c6ecd-df58-462e-a447-38c620a12fe1 Version: 2.4.60878 ValidUntil: 2180-12-25 11:58:44
UUID:         7f52060d-4af4-4ca7-8fe7-3619ee7f6bfb
Version:      24.9.1-candidate.12
Extra versions:
Tags:
Creation Date:  2024-11-27 12:58:40 +0530 IST (6 days ago)
Role:         consolidated-bng
Platform:     q2a
Model:        s9510-28dc
Format:       onl-installer
Architecture: amd64
Filename: rtbrick-onl-installer/rtbrick-onl-installer-consolidated-bng-q2a-s9510-28dc-24.9.1-candidate.12.d
FullPath/URL: /var/cache/rtbrick/imagestores/847c6ecd-df58-462e-a447-38c620a12fe1/rtbrick-onl-installer/rtbrick-onl-installer-consolidated-bng-q2a-s9510-28dc-24.9.1-candidat…
SHA512:       1bf41a8f96933b73af2ce9c3484766db373ab87118b1aa9ef8
Base Image: 5117031a-53b9-4e49-9500-602f2757ebce
Embedded Packages: 16
Embedded Images: 1
IsLayered:    false
Cached:       false
ExtractedPath:
The sudo rtb-image show command displays only symlink information, so you need to copy the source file.

Once the image has been downloaded successfully, proceed to install it using ONIE. For details, see Installing ONL Manually.downloaded