From 98db0e634e8cb4cb2dc53f8b476f91f0304b82fc Mon Sep 17 00:00:00 2001 From: Reuben Miller Date: Sat, 3 Feb 2024 17:39:05 +0100 Subject: [PATCH 1/5] docs: update rugpi instructions to align with rugpi v0.6 Signed-off-by: Reuben Miller --- .../building-image/rugpi/tutorial.md | 118 ++++++++++++------ 1 file changed, 77 insertions(+), 41 deletions(-) diff --git a/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md b/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md index 3ee0c3cfdff..49a84915e97 100644 --- a/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md +++ b/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md @@ -13,7 +13,8 @@ The instructions on this page can be used to build images for the following devi * Raspberry Pi 1 (32 bit) * Raspberry Pi 2 (64 bit) * Raspberry Pi 3 (64 bit) -* Raspberry Pi 4 (64 bit) +* Raspberry Pi 4 / 400 (64 bit) +* Raspberry Pi Compute Module 4 (64 bit) * Raspberry Pi 5 (64 bit) * Raspberry Pi Zero W (32 bit) * Raspberry Pi Zero 2W (64 bit) @@ -36,8 +37,29 @@ Images can be built using Rugpi using a CI Workflow. An example for a Github Wor The [tedge-rugpi-images](https://github.com/thin-edge/tedge-rugpi-image) project includes out of the box configurations to perform robust Over-the-Air Operating System updates. +The [tedge-rugpi-core](https://github.com/thin-edge/tedge-rugpi-core) project contains the %%te%% specific recipes which are used to build the image. + Feel free to clone the project if you want to make your own customizations, however please always refer back to the project if you run into any problems (as it may have changed in the meantime). +### Pre-requisites + +To run the project tasks, you will need to install a command line tool called [just](https://just.systems/man/en/chapter_5.html). + +You can install just using on of the following commands: + +```sh tab={"label":"homebrew"} +brew install just +``` + +```sh tab={"label":"cargo"} +cargo install just +``` + +```sh tab={"label":"script"} +curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | sudo bash -s -- --to /usr/bin +``` + +For other installation possibilities check out the [just documentation](https://just.systems/man/en/chapter_4.html). ### Cloning the project @@ -48,92 +70,103 @@ Feel free to clone the project if you want to make your own customizations, howe cd tedge-rugpi-image ``` -2. Install [just](https://just.systems/man/en/chapter_5.html) which is used to run different tasks provided by the project +2. Create a custom `.env` file which will be used to store secrets ```sh - curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | sudo bash -s -- --to /usr/bin + cp env.template .env ``` - Check out the [justfile website](https://just.systems/man/en/chapter_5.html) for more installation options. - -### Customizing your own image - -1. Fork the project - -2. Edit the authorized ssh keys for each profile + The `.env` file will not be committed to the repo - Edit the `root_authorized_keys` under each toml file in the `profiles/` directory, and add the public ssh keys whom you want to grant ssh access to for the device. Below shows one example. +3. Add your public ssh key to the `.env` file - ```toml title="file: profiles/default.toml" - #... + Adding public SSH keys to the project will allow you to access after the image is flashed to the device (which is critical for the onboarding process). The SSH keys are provided in the form of environment variables where the variable names start with `SSH_KEY_`. - [parameters.ssh] - root_authorized_keys = """ - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDfhQGWWw73ponAokdNSRZ5cQc9/CIX1TLQgYlr+BtObKoO4UNFP1YSbgK03GjhjeUid+QPmV+UURqxQTqLQoYWqUFP2CYkILFccVPmTvx9HLwupI+6QQKWfMDx9Djfph9GzInymaA5fT7hKppqittFrC/l3lkKgKTX5ohEOGshIbRgtgOYIaW3ByTx3urnaBbYCIgOyOZzSIyS0dUkwsiLu3XjPspgmn3Fs/+vofT/yhBe1carW0UM3ivV0JFfJzrxbCl/F7I2qwfjZXsypjkwlpNupUMuo3xPMi8YvNvyEu4d+IEAqO1dCcdGcxlkiHxrdITIpVLt5mjJ2LauHE/H bootstrap - """ + For example: - # ... + ``` + SSH_KEYS_bootstrap="ssh-rsa xxxxxxx" + SSH_KEYS_user2="ssh-rsa xxxxxxx" + SSH_KEYS_user3="ssh-rsa xxxxxxx" ``` :::tip This step is critical as it will enable you to connect via SSH to your device to perform tasks such as onboarding! If you don't set your ssh public key in the authorized keys, you then need to connect your device to a monitor/display and keyboard in order to perform the onboarding. ::: -3. Commit the changes +4. Optional: Add Wifi ssid/password - only required for the initial flashing of the device + + If your device does not have an ethernet adapter, or you the device to connect to a Wifi network for onboarding, then you will have to add the Wifi credentials to the `.env` file. -4. You can now add any custom recipes to your project if you want to include additional packages in your image, or configure items. + Below shows the environment variables that should be added to the `.env` file. + + ```sh + SECRETS_WIFI_SSID=example + SECRETS_WIFI_PASSWORD=yoursecurepassword + ``` + + **Note** + + The Wifi credentials only need to be included in the image that is flashed to the SD card. Subsequent images don't need to included the Wifi credentials, as the network connection configuration files are persisted across images. + + If an image has Wifi credentials baked in, then you should not make this image public, as it would expose your credentials! + + - See the [Rugpi System Customization](https://oss.silitics.com/rugpi/docs/guide/system-customization) docs for details on how to do this or follow clues from some of the existing recipes included in the [tedge-rugpi-images](https://github.com/thin-edge/tedge-rugpi-image) project. ### Building an image -:::info -Currently building is only supported on a Linux environment. It is strongly encouraged to use the Github workflow to build the image. -::: +Building an image will produce a `.xz` file which can either by flashed to an SD card (or device). Afterwards your device will be enable to apply the same type of image via OTA updates. + +Images can be built in MacOS or Linux environments (including WSL 2), however if you have problems building the image, then you can build the images using the Github workflow after forking the project. + 1. Build an image for your device (machine) ```sh tab={"label":"Pi\tZero"} - just IMAGE_ARCH=armhf PROFILE=armhf VARIANT=pi01 build-all + just build-pizero ``` ```sh tab={"label":"Pi\t1"} - just IMAGE_ARCH=armhf PROFILE=armhf VARIANT=pi01 build-all + just build-pi1 ``` ```sh tab={"label":"Pi\t2"} - just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi023 build-all + just build-pi2 ``` ```sh tab={"label":"Pi\t3"} - just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi023 build-all + just build-pi3 ``` ```sh tab={"label":"Pi\tZero2W"} - just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi023 build-all + just build-pizero2w ``` ```sh tab={"label":"Pi\t4\t(With\tFirmware)"} - just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi4 build-all + just build-pi4-include-firmware ``` ```sh tab={"label":"Pi\t4\t(Without\tFirmware)"} - just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi45 build-all + just build-pi4 ``` ```sh tab={"label":"Pi\t5"} - just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi45 build-all + just build-pi5 ``` - :::info + :::note See the [tips](#raspberry-pi-4-image-selection) for helping you select which Raspberry Pi 4 image is suitable for you (e.g. with or without the EEPROM firmware update) ::: -2. Inspect the built image +2. Flash the base image using the instructions on the [Flashing an image](../../flashing-an-image.md) page - ```sh - ls -ltr build/*.img - ``` -3. Flash the base image using the instructions on the [Flashing an image](../../flashing-an-image.md) page +:::info +The above tasks are actually just user-friendly helpers to make it easier to select the right image for your device, so some build-xxx tasks actually build the same output image (e.g. `build-pi4` and `build-pi5` produce the same image). + +If you want more control over the process you can use the command, and select one of the images as defined in the [rugpi-bakery.toml](https://github.com/thin-edge/tedge-rugpi-image/blob/main/rugpi-bakery.toml) + +For more information about Rugpi repositories, layers and overall concepts please read the [official Rugpi documentation](https://oss.silitics.com/rugpi/docs/guide/system-customization/). +::: ## Tips @@ -186,7 +219,7 @@ INFO[0000] socket: unix:///Users/johnsmith/.colima/default/docker.sock Try running the command with sudo. On some systems sudo is required to properly create the compressed xz file. -For exampke, the `build-all` task can be called with sudo: +For example, the `build-all` task can be called with sudo: ```sh sudo just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi45 build-all @@ -199,11 +232,14 @@ Raspberry Pi 4 devices need to have their (EEPROM) firmware updated before the O You can build an image which includes the required EEPROM firmware to enable the tryboot feature, however this image can only be used to deploy to Raspberry Pi 4 devices (not Raspberry Pi 5!) ```sh -just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi4 build-all +just build-pi4-include-firmware ``` After the above image has been flashed to the device once, you can switch back to the image without the EEPROM firmware so that the same image can be used for both Raspberry Pi 4 and 5. ```sh -just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi45 build-all +just build-pi4 + +# or +just build-pi5 ``` From 6f6d025b198d99490bb9a7a92b7193d37aa4a669 Mon Sep 17 00:00:00 2001 From: Reuben Miller Date: Mon, 5 Feb 2024 14:06:17 +0100 Subject: [PATCH 2/5] remove permission denied error as the compress script will use sudo if necessary Signed-off-by: Reuben Miller --- .../building-image/rugpi/tutorial.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md b/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md index 49a84915e97..fb4269119c9 100644 --- a/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md +++ b/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md @@ -214,17 +214,6 @@ INFO[0000] mountType: virtiofs INFO[0000] socket: unix:///Users/johnsmith/.colima/default/docker.sock ``` - -### Permission denied error caused by xz - -Try running the command with sudo. On some systems sudo is required to properly create the compressed xz file. - -For example, the `build-all` task can be called with sudo: - -```sh -sudo just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi45 build-all -``` - ### Raspberry Pi 4 image selection Raspberry Pi 4 devices need to have their (EEPROM) firmware updated before the OTA updates can be issued. This is because the initial Raspberry Pi 4's were released without the [tryboot feature](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#fail-safe-os-updates-tryboot). The tryboot feature is used by Rugpi to provide the reliable partition switching between the A/B partitions. Raspberry Pi 5's have support for tryboot out of the box, so they do not require a EEPROM upgrade. From 2fbb29453d2b5488b93dc6ab16c3386da109ff22 Mon Sep 17 00:00:00 2001 From: Reuben Miller Date: Mon, 5 Feb 2024 14:08:35 +0100 Subject: [PATCH 3/5] add notes about ssid/password in images as a tip Signed-off-by: Reuben Miller --- .../firmware-management/building-image/rugpi/tutorial.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md b/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md index fb4269119c9..fce082aa98c 100644 --- a/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md +++ b/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md @@ -105,11 +105,11 @@ For other installation possibilities check out the [just documentation](https:// SECRETS_WIFI_PASSWORD=yoursecurepassword ``` - **Note** - + :::tip The Wifi credentials only need to be included in the image that is flashed to the SD card. Subsequent images don't need to included the Wifi credentials, as the network connection configuration files are persisted across images. If an image has Wifi credentials baked in, then you should not make this image public, as it would expose your credentials! + ::: From be3aebc551c3dc370e515f03798b68c03ff1187b Mon Sep 17 00:00:00 2001 From: Reuben Miller Date: Mon, 5 Feb 2024 14:10:55 +0100 Subject: [PATCH 4/5] reword wifi section Signed-off-by: Reuben Miller --- .../firmware-management/building-image/rugpi/tutorial.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md b/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md index fce082aa98c..66becc69b50 100644 --- a/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md +++ b/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md @@ -94,9 +94,9 @@ For other installation possibilities check out the [just documentation](https:// This step is critical as it will enable you to connect via SSH to your device to perform tasks such as onboarding! If you don't set your ssh public key in the authorized keys, you then need to connect your device to a monitor/display and keyboard in order to perform the onboarding. ::: -4. Optional: Add Wifi ssid/password - only required for the initial flashing of the device +4. Optional: Add Wifi ssid/password - If your device does not have an ethernet adapter, or you the device to connect to a Wifi network for onboarding, then you will have to add the Wifi credentials to the `.env` file. + If your device does not have an ethernet adapter, or if you want to connect the device to a Wifi network for onboarding, then you will have to add the Wifi credentials to the `.env` file. Below shows the environment variables that should be added to the `.env` file. From 7270cdc6049d33d2f049f24b61836e4eadaaa984 Mon Sep 17 00:00:00 2001 From: Reuben Miller Date: Mon, 5 Feb 2024 14:23:14 +0100 Subject: [PATCH 5/5] add detail about where the ssh keys are added to Signed-off-by: Reuben Miller --- .../firmware-management/building-image/rugpi/tutorial.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md b/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md index 66becc69b50..eb2e8205a71 100644 --- a/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md +++ b/docs/src/extend/firmware-management/building-image/rugpi/tutorial.md @@ -80,14 +80,12 @@ For other installation possibilities check out the [just documentation](https:// 3. Add your public ssh key to the `.env` file - Adding public SSH keys to the project will allow you to access after the image is flashed to the device (which is critical for the onboarding process). The SSH keys are provided in the form of environment variables where the variable names start with `SSH_KEY_`. + Adding public SSH keys to the project will allow you to access after the image is flashed to the device (which is critical for the onboarding process). The SSH keys are provided in the form of environment variables where the variable names start with `SSH_KEY_` and are added to the authorized keys for the root user, e.g. `/root/.ssh/authorized_keys`. For example: ``` SSH_KEYS_bootstrap="ssh-rsa xxxxxxx" - SSH_KEYS_user2="ssh-rsa xxxxxxx" - SSH_KEYS_user3="ssh-rsa xxxxxxx" ``` :::tip