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.
The process of downloading software involves the following tasks:
1. Generating a Client Certificate
2. Uploading the Certificate to the Self-Service Portal
3. Obtaining Approval and Verification of Client Certificate
4. Identifying and Activating the Image Repository
5. Installing the rtb-image Tool and Verifying Access to Image Stores
6. Downloading the Host Image
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)
1.2. Installing the rtb-apt Tool
1.3. Generating a TLS Client Certificate
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
1.2.2. Downloading and Installing the rtb-apt Tool
1.2.3. Verifying the Version of the rtb-apt Tool
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
aptto validate package repositories. To install GPG, enter the following command:
sudo apt install gnupg
-
HTTPS support for
aptis 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.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:
-
Log in to Self-Service Portal.
-
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.
-
Click the Upload certificate button in the organization’s certificate list view to upload a new client certificate.
-
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.
-
Click the Upload certificate button to upload a new certificate.
3. Obtaining Approval and verification of the Client Certificate
-
RtBrick reviews and approves the client’s certificate that is uploaded on the Self-Service portal.
-
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 Host 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
5.2.2. Activating a Restricted Image Store
5.2.3. Verifying Access to Image Stores
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 Host Image
Image stores contain the Host installer images.
To download Host installer images, perform the following steps:
6.1. Updating the Local Cached Copy of the Remote Image Store
6.2. Finding the Host Image
6.3. Pulling the Host Image
6.4. Verifying the Location of the Downloaded Image
6.1. Updating the Local Cached Copy of the Remote Image Store
Enter the following command to update the local cached copy of the remote image store for RBFS container and Host 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.140875 ValidUntil: 2525-06-20 11:58:44
6.2. Finding the Host Image
To find the Host 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 Host image details for UfiSpace S9510-28DC Multiservice Edge image.
$ sudo rtb-image list -f host-installer --role multiservice-edge --ver-range latest --model s9510-28dc Store: /var/cache/rtbrick/imagestores/847c6ecd-df58-462e-a447-38c620a12fe1 Version: 2.4.140885 ValidUntil: 2525-07-20 11:58:44 ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ │ UUID Version Role Model Platform Format Cached │ │──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────│ │ 81c3d77c-a4cd-4ed0-903d-d5d523d81415 25.3.1-candidate.2 multiservice-edge s9510-28dc q2a host-install… false │ └──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
6.3. Pulling the Host Image
There are two options available for downloading the Host 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 Host image, use the UUID (for example, 81c3d77c-a4cd-4ed0-903d-d5d523d81415) of the Host 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 81c3d77c-a4cd-4ed0-903d-d5d523d81415 bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.2.sha512 234 B / 234 B [==============================================================================] 100.00% 0s bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.2.asc 833 B / 833 B [=================================================================================] 100.00% 0s bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.2 1.38 GiB / 1.38 GiB [==============================================================================] 100.00% 18s bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.2: decompressing 100 B / 100 B [======================================================================] 100.00% 8s 81c3d77c-a4cd-4ed0-903d-d5d523d81415 downloaded as /home/user
The image will be downloaded to the current working directory under the rtbrick-host-installer/ directory as shown below:
$ ls -al total 13628 drwxr-xr-x 21 rtbuser rtbuser 4096 Sep 9 07:37 . drwxr-xr-x 19 root root 4096 Jun 6 2024 .. drwxr-xr-x 2 rtbuser rtbuser 4096 Sep 9 09:15 rtbrick-host-installer $ ls -al total 2909948 drwxr-xr-x 2 rtbuser rtbuser 4096 Sep 9 09:15 . drwxr-xr-x 21 rtbuser rtbuser 4096 Sep 9 07:37 .. rw-r--r- 1 rtbuser rtbuser 1480346261 Sep 9 09:15 bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.2 rw-r--r- 1 rtbuser rtbuser 833 Sep 9 09:15 bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.2.asc rw-r--r- 1 rtbuser rtbuser 234 Sep 9 09:15 bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.2.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/ 81c3d77c-a4cd-4ed0-903d-d5d523d81415 bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.2.sha512 234 B / 234 B [==============================================================================] 100.00% 0s bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.2.asc 833 B / 833 B [=================================================================================] 100.00% 0s bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.2 1.38 GiB / 1.38 GiB [==============================================================================] 100.00% 18s bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.2: decompressing 100 B / 100 B [======================================================================] 100.00% 0s 81c3d77c-a4cd-4ed0-903d-d5d523d81415 downloaded as /home/supervisor $ cd /home/supervisor $ ls -al total 13628 drwxr-xr-x 21 prasanna prasanna 4096 Sep 9 07:37 . drwxr-xr-x 19 root root 4096 Jun 6 2024 .. drwxr-xr-x 2 prasanna prasanna 4096 Sep 9 09:15 rtbrick-host-installer $ ls -al total 2909948 drwxr-xr-x 2 prasanna prasanna 4096 Sep 9 09:15 . drwxr-xr-x 21 prasanna prasanna 4096 Sep 9 07:37 .. rw-r--r- 1 prasanna prasanna 1480346261 Sep 9 09:15 bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.2 rw-r--r- 1 prasanna prasanna 833 Sep 9 09:15 bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.2.asc rw-r--r- 1 prasanna prasanna 234 Sep 9 09:15 bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.2.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 81c3d77c-a4cd-4ed0-903d-d5d523d81415 Store: /var/cache/rtbrick/imagestores/847c6ecd-df58-462e-a447-38c620a12fe1 Version: 2.4.140885 ValidUntil: 2525-07-20 11:58:44 UUID: 81c3d77c-a4cd-4ed0-903d-d5d523d81415 Version: 25.3.1-candidate.2 Extra versions: Tags: Creation Date: 2025-08-27 07:25:59 +0000 UTC (1 week ago) Role: multiservice-edge Platform: q2a Model: s9510-28dc Format: host-installer Architecture: amd64 Filename: rtbrick-host-installer/bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate.2 FullPath/URL: /var/cache/rtbrick/imagestores/847c6ecd-df58-462e-a447-38c620a12fe1/rtbrick-host-installer/bookworm-installer-multiservice-edge-q2a-s9510-28dc-25.3.1-candidate… SHA512: 897eb424e8e17afabd96e0fdb6542ff9848d51d17fc760f36c8288964f6ba2f653fe5ffd5f3be18e113bf964ee79f3b6765aa18eeec18a27c3ee07c082b6aef8 Base Image: - Embedded Packages: 15 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 Host Manually downloaded.