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:
Generating a Client Certificate
RtBrick provides the rtb-apt tool to generate a client certificate. This section contains the following topics:
About 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 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.
Installing the rtb-apt Tool
This section contains the following topics:
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
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
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.
Uploading the Client Certificate to the Self-Service Portal
After generating the TLS Client Certificate, upload it to the Certificates section on Self-Service Portal.
To upload a new client certificate, go to Self-Service Portal, and then click the "Upload certificate" button in the organization’s certificate list view. For details, see the "Client Certificate Management via Self-Service Portal" section below.
| 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. |
Client Certificate Management
The access to RtBrick image repository is enabled by installing a client certificates. A customer creates a client certificate as outlined in this guide and uploads the public key to the portal. RtBrick reviews and approves the client certificate.
Working with the certificate list
The organization’s certificate list shows all certificates of that particular organization. To view the certificate list, perform the following steps:
-
Log in to Self-Service Portal.
-
Click Certificates on the left navigation panel. The Certificates list page appears.
The filter options allows filtering certificates by their distinguished name or lifecycle status.
Uploading a new client certificate
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 and click Upload Certificate to upload a new certificate. The description field is optional and provides extra information about the certificate.
Click the Upload certificate button to upload a new certificate.
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
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:
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 releases/23.8.1 rtbrick-tools ubuntu jammy No No releases/23.9.1 rtbrick-tools ubuntu jammy No No releases/23.10.1 rtbrick-tools ubuntu jammy No No releases/23.11.1 rtbrick-tools ubuntu jammy No No releases/23.12.1 rtbrick-tools ubuntu jammy No No < ......................................... >
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
Verifying the Active Repositories
To verify the active repositories, use the "sudo rtb-apt repo list" command.
❯ sudo rtb-apt repo list Group Repository Distribution Release Active Restricted releases/latest rtbrick-tools ubuntu jammy Yes Yes <<<<<<<< releases/23.8.1 rtbrick-tools ubuntu jammy No No releases/23.9.1 rtbrick-tools ubuntu jammy No No < ......................................... >
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:
Installing the rtbrick-imgstore Package
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. < ......................................... >
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.
| For more information about the the RBFS image formats and ONL image installation for supported hardware, refer to section Image formats and ONL image installation for supported hardware. |
This section contains the following topics:
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 < ......................................... >
Activating a Restricted Image Store
The following example shows how to activate a (possibly restricted) image store:
❯ sudo rtb-image stores activate 0
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
Downloading the ONL Image
Image stores contain the ONL installer images.
To download ONL installer images, perform the following steps:
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
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
Pulling the ONL Image
To download the ONL image, use the UUID (for example, db568345-a313-4abd-8c14-4970396d048f) of the ONL image in the "sudo rtb-image pull" command.
❯ sudo rtb-image pull db568345-a313-4abd-8c14-4970396d048f rtbrick-onl-installer-consolidated-bng-q2a-24.9.1-g8daily.20220605220700+Bmaster.C2f0eae65.d.sha512 244 B / 244 B [===================================================================] 100.00% 0s
Displaying the Location of the Downloaded Image
The following example shows how to view the Local Image Path.
❯ sudo rtb-image show db568345-a313-4abd-8c14-4970396d048f Store: /var/cache/rtbrick/imagestores/847c6ecd-df58-462e-a447-38c620a12fe1 Version: 2.4.60878 ValidUntil: 2180-12-25 11:58:44 UUID: db568345-a313-4abd-8c14-4970396d048f 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:
After the image is download successfully, you have to set up an HTTP server (or by any other means) that will make available the downloaded images for ONIE to use. To continue with installing the downloaded image using ONIE, see Installing ONL Manually.