From 7b10cd612783e7bc5136f2f4ba6b5f25ea511d81 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maximilian=20K=C3=B6hl?= Date: Sun, 30 Jun 2024 23:02:23 +0200 Subject: [PATCH] docs: consolidate docs --- www/docs/advanced/device-management.md | 22 +++++++++++++++++++ www/docs/advanced/signed-updates.md | 7 ++++++ www/docs/guide/over-the-air-updates.md | 9 ++++---- www/docs/integrations/_category_.json | 8 ------- www/docs/integrations/index.md | 5 ----- www/docs/integrations/mender.md | 13 ----------- www/docs/integrations/thin-edge.md | 10 --------- .../version-0.6/guide/over-the-air-updates.md | 4 ++-- 8 files changed, 35 insertions(+), 43 deletions(-) create mode 100644 www/docs/advanced/device-management.md create mode 100644 www/docs/advanced/signed-updates.md delete mode 100644 www/docs/integrations/_category_.json delete mode 100644 www/docs/integrations/index.md delete mode 100644 www/docs/integrations/mender.md delete mode 100644 www/docs/integrations/thin-edge.md diff --git a/www/docs/advanced/device-management.md b/www/docs/advanced/device-management.md new file mode 100644 index 0000000..b4bd71c --- /dev/null +++ b/www/docs/advanced/device-management.md @@ -0,0 +1,22 @@ +# Device Management + +Rugpi provides the reliable foundation for building images, OTA updates, and state management. +To manage devices remotely, Rugpi integrates well with existing off-the-shelf device management solutions. +Currently, Rugpi provides ready-made integrations with [thin-edge.io](https://thin-edge.io/) and [Mender](https://mender.io/). +When building a device with Rugpi, you can also switch between those at any point in time. + +## Thin-edge.io + +[Thin-edge.io](https://thin-edge.io/) is an open-source, cloud-agnostic IoT framework designed for resource constraint devices. +It provides an abstraction layer to interface with different providers of IoT management solutions such as [Cumulocity IoT](https://www.cumulocity.com/guides/concepts/introduction/), [Azure IoT](https://azure.microsoft.com/en-us/solutions/iot), and [AWS IoT](https://aws.amazon.com/iot/). +Thin-edge.io officially supports Rugpi to build and deploy images. +To learn more, checkout the [thin-edge.io Rugpi reference repository](https://github.com/thin-edge/tedge-rugpi-image). + +## Mender + +Rugpi can be used to build images for use with [Mender's](https://mender.io/) device management solution. +Using Rugpi over [Mender's conversion approach](https://docs.mender.io/operating-system-updates-debian-family/convert-a-mender-debian-image) has the advantage that Rugpi's modern image building workflow and state management can be used. +In addition, it works for 64-bit Raspberry Pi OS, which `mender-convert` does not support,[^1] and on newer Raspberry Pi's the `tryboot` feature can be used to deploy updates to the boot partition, including changes to device tree overlays in `config.txt`. +To learn more, checkout the [Rugpi reference repository for the Mender integration](https://github.com/silitics/rugpi-template-mender). + +[^1]: At the time of writing. For updates, see [this issue in Mender's issue tracker](https://northerntech.atlassian.net/browse/MEN-5634). diff --git a/www/docs/advanced/signed-updates.md b/www/docs/advanced/signed-updates.md new file mode 100644 index 0000000..2b43886 --- /dev/null +++ b/www/docs/advanced/signed-updates.md @@ -0,0 +1,7 @@ +# Signed Updates + +In contrast to other update solutions, Rugpi is intentionally kept simple and does not include its own signature mechanism or HTTP client. Following the UNIX philosophy, Rugpi accepts streaming updates via `stdin`. This enables the usage of proven software such as `curl` and `wget` to stream updates via HTTP and also facilitates the integration into custom update workflows. To realize verified updates, Rugpi provides an option `--check-hash` which can be used to check the SHA256 of a (streamed) update. Based upon this mechanism, signed updates can then be realized in various ways, for instance, by using GPG or OpenSSL signatures. + +In a typical setup, you would create an *update manifest* which contains the hash of the update and an URL from where to download the update. You would then sign this manifest, e.g., with GPG or OpenSSL. The update workflow would first check the signature and then invoke `rugpi update` with `--check-hash` and stream in the update, e.g., with `curl` or `wget`, to it. This ensures that the update you install is indeed the one described in the signed manifest. + +Note that this mechanism is very flexible and allows us to build on trusted tools in a simple way. You can also combine an update and the signed manifest in a `.tar` archive and process that in a streaming fashion as part of your update workflow. In the future, we may also consider adding something like that to Rugpi itself. diff --git a/www/docs/guide/over-the-air-updates.md b/www/docs/guide/over-the-air-updates.md index f42342d..9ad24d6 100644 --- a/www/docs/guide/over-the-air-updates.md +++ b/www/docs/guide/over-the-air-updates.md @@ -66,20 +66,19 @@ Note that a persistent overlay that may exist for the spare partition is deleted To avoid the overlay from being discarded, use the `--keep-overlay` option when installing the update. Please be aware that this may lead to incompatibilities between the overlay and the freshly installed system. -Rugpi also has experimental support for streaming updates directly to the SD card instead of first storing the image and then installing it. -To this end, use the option `--stream`. -With `--stream`, you can use `-` as artifact path to install an image streamed via stdin to Rugpi Ctrl. +Rugpi also has support for streaming updates directly to the SD card instead of first storing the image and then installing it. +You can use `-` as artifact path to install an image streamed via stdin to Rugpi Ctrl. This also allows using compressed images. For instance, to download, decompress, and install an image on-the-fly, use: ```shell -curl | xz -d | rugpi-ctrl update install --stream - +curl | xz -d | rugpi-ctrl update install - ``` In case the internet connection is unstable, you may also want to use ```shell -wget -q -t 0 -O - | rugpi-ctrl update install --stream - +wget -q -t 0 -O - | rugpi-ctrl update install - ``` to retry downloading indefinitely. For further details, we refer to the manpage of `wget`. diff --git a/www/docs/integrations/_category_.json b/www/docs/integrations/_category_.json deleted file mode 100644 index 86dc34e..0000000 --- a/www/docs/integrations/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Integrations", - "position": 30, - "link": { - "type": "doc", - "id": "index" - } -} \ No newline at end of file diff --git a/www/docs/integrations/index.md b/www/docs/integrations/index.md deleted file mode 100644 index d5bed6d..0000000 --- a/www/docs/integrations/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# Integrations - -Rugpi provides the reliable foundation for building images, OTA updates, and state management. -To manage devices remotely, Rugpi integrates well with existing off-the-shelf solutions. -This part of the documentations list such integrations. \ No newline at end of file diff --git a/www/docs/integrations/mender.md b/www/docs/integrations/mender.md deleted file mode 100644 index 3b55be7..0000000 --- a/www/docs/integrations/mender.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Mender - -Rugpi can be used to build images for use with [Mender's](https://mender.io/) device management solution. -Using Rugpi over [Mender's conversion approach](https://docs.mender.io/operating-system-updates-debian-family/convert-a-mender-debian-image) has the advantage that Rugpi's modern image building workflow and state management can be used. -In addition, it works for 64-bit Raspberry Pi OS, which `mender-convert` does not support,[^1] and on newer Raspberry Pi's the `tryboot` feature can be used to deploy updates to the boot partition, including changes to device tree overlays in `config.txt`. - -To apply updates via Mender, a custom Mender update module is necessary. - -[^1]: At the time of writing. For updates, see [this issue in Mender's issue tracker](https://northerntech.atlassian.net/browse/MEN-5634). diff --git a/www/docs/integrations/thin-edge.md b/www/docs/integrations/thin-edge.md deleted file mode 100644 index ecfb691..0000000 --- a/www/docs/integrations/thin-edge.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -sidebar_position: 0 ---- - -# Thin-edge.io - -[Thin-edge.io](https://thin-edge.io/) is an open-source, cloud-agnostic IoT framework designed for resource constraint devices. -It provides an abstraction layer to interface with different providers of IoT management solutions such as [Cumulocity IoT](https://www.cumulocity.com/guides/concepts/introduction/), [Azure IoT](https://azure.microsoft.com/en-us/solutions/iot), and [AWS IoT](https://aws.amazon.com/iot/). -Thin-edge.io officially supports Rugpi to build and deploy images. -To learn more, checkout the [thin-edge.io Rugpi reference repository](https://github.com/thin-edge/tedge-rugpi-image). \ No newline at end of file diff --git a/www/versioned_docs/version-0.6/guide/over-the-air-updates.md b/www/versioned_docs/version-0.6/guide/over-the-air-updates.md index c4e9cf8..85c445b 100644 --- a/www/versioned_docs/version-0.6/guide/over-the-air-updates.md +++ b/www/versioned_docs/version-0.6/guide/over-the-air-updates.md @@ -72,13 +72,13 @@ This also allows using compressed images. For instance, to download, decompress, and install an image on-the-fly, use: ```shell -curl | xz -d | rugpi-ctrl update install --stream - +curl | xz -d | rugpi-ctrl update install - ``` In case the internet connection is unstable, you may also want to use ```shell -wget -q -t 0 -O - | rugpi-ctrl update install --stream - +wget -q -t 0 -O - | rugpi-ctrl update install - ``` to retry downloading indefinitely. For further details, we refer to the manpage of `wget`.