# SWUpdate

**URL:** <https://hub.mender.io/t/swupdate/6953>\
**Category:** Update Modules\
**Created:** [June 15, 2024, 8:30am UTC](https://hub.mender.io/t/swupdate/6953 "2024-06-15T08:30:35Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![TheYoctoJester](https://yyz2.discourse-cdn.com/flex036/user_avatar/hub.mender.io/theyoctojester/32/1444_2.png) [@TheYoctoJester](https://hub.mender.io/u/TheYoctoJester)\
**Post date:** [June 15, 2024, 8:30am UTC](https://hub.mender.io/t/swupdate/6953/1 "2024-06-15T08:30:35Z")

</div>

## Description

There is a variety of client-only solutions for installing update artifacts to embedded Linux devices, such as SWupdate or RAUC which do not offer a remote management solution. Those can be wrapped in an Update Module to enable OTA deployments, while keeping known good working integrations intact.

Example use-cases:

- Brownfield migration of existing device fleets using a client-only update solution
- Wrapping a custom flashing solution, as sometimes required for special hardware

This Update Module provides a sample implementation to deploy SWUpdate artifacts using Mender, but it can be easily adapted to other client solutions.

## Specification

| Specification | |
| --- | --- |
| Module name | swu |
| Supports rollback | no |
| Requires reboot | configurable |
| Artifact generation script | no |
| Full operating system updater | no |
| Source code | [https://github.com/mendersoftware/mender-update-modules/master/swu](https://github.com/mendersoftware/mender-update-modules/master/swu) |
| Maintainer | josef.holzmayr@northern.tech |

**Please be aware that Mender Update modules are meant to update parts of the operating system and if not configured properly they could potentially delete parts or even the full operating system. Always inspect the code carefully and only test modules on device that you can recover easily.**

**It is not recommended to install a Mender Artifact on your workstation**

## Prepare the device

This section describes how to setup your target device, i.e. the device to be updated. This will also be referred to as the device environment.

All commands outlined in this section should be run in the device environment.

### Prerequisites

This update module has the following prerequisites for the device environment:

- [Mender client](https://docs.mender.io/client-installation/install-with-debian-package?target=_blank), version 2.0 or later
- [SWUpdate client](https://swupdate.org/)
- [jq](https://jqlang.github.io/jq/)

This Update Module has the following prerequisites for the development environment:

- [Install mender-artifact](https://docs.mender.io/artifact-creation/modify-an-artifact?target=_blank), version 3.0.0 or later
- [jq](https://jqlang.github.io/jq/)

### Install the Update Module

Download the latest version of this Update Module by running:

```bash
mkdir -p /usr/share/mender/modules/v3 && wget -P /usr/share/mender/modules/v3 https://raw.githubusercontent.com/mendersoftware/mender-update-modules/master/swu/module/swu && chmod +x /usr/share/mender/modules/v3/swu

```

## Prepare the development environment on your workstation

This section describes how to set up your development environment on your workstation.

All commands outlined in this section should be run in the development environment.

### Create artifact

To download `swu-artifact-gen`, run the following:

```auto
wget https://raw.githubusercontent.com/mendersoftware/mender-update-modules/master/install_snap/module-artifact-gen/install_snap-artifact-gen && chmod +x swu-artifact-gen

```

Generate Mender Artifacts using the following command:

```auto
ARTIFACT_NAME="my-update-1.0"
DEVICE_TYPE="my-device-type"
./swu-artifact-gen \
    --artifact-name ${ARTIFACT_NAME} \
    --device-type ${DEVICE_TYPE} \
    <name of swu file(s)> ...

```

### Optional reboot

The SWU Update Module supports rebooting after artifact installation. If this is required for the packaged SWU file(s), add the `--reboot` flag to the `swu-artifact-gen` invocation.

### Possible future improvements

- rollback support
- automatic determination of metadata from SWU file(s)
- enforced ordering of multiple SWUs
- streaming support

You can either deploy this Artifact in managed mode with the Mender server (upload it under Releases in the server UI) or by using the Mender client only in [Standalone deployments](https://docs.mender.io/artifact-creation/standalone-deployment?target=_blank).

### Artifact technical details

- The artifact can include an arbitrary number of `*.swu` files, but does not explicitly guarantee an installation order. The `swupdate` invocation uses a `*.swu` wildcard.

### Creating a sample `.swu` file

In order to test this Update Module, having a device independent `swu` artifact is useful. To create one, you need the following:

A payload file. We will use this `swu-demo.txt` as an example:

```auto
Demo payload for the Mender SWU Update Module!

```

The `sw-description` file:

```auto
software =
{
    description = "Demo for Mender SWU Update Module"

    hardware-compatibility: ["1.0"];

    files: (
        {
            filename = "swu-demo.txt";
            path = "/opt/swu-demo.txt";
			properties = {
				create-destination = "true";
			}
        }
    );
}

```

An `swu` file is at its heart a `cpio` archive, with the `sw-description` file coming first. You can create one using the following script:

```auto
#!/bin/bash

VERSION="1.0"
NAME="swu-demo"

OUTFILE="${NAME}_${VERSION}.swu"
echo "creating SWU artifact ${OUTFILE}"

if [-f "$OUTFILE"]; then
    echo "$OUTFILE already exists, moving to $OUTFILE.bak"
	mv $OUTFILE $OUTFILE.bak
fi

FILES="sw-description swu-demo.txt"

for i in $FILES;do
    echo $i;done | cpio -ov -H crc > ${OUTFILE}

```

The resulting `swu-demo_1.0.swu` can be used for the `swu-artifact-gen` script as described above.

---

<div class="post-metadata">

**Author:** ![dwalkes](https://yyz2.discourse-cdn.com/flex036/user_avatar/hub.mender.io/dwalkes/32/41_2.png) [@dwalkes](https://hub.mender.io/u/dwalkes)\
**Post date:** [June 25, 2024, 12:54am UTC](https://hub.mender.io/t/swupdate/6953/2 "2024-06-25T00:54:48Z")

</div>

@TheYoctoJester thanks for sharing this, I think this could be super useful.

Regarding:

> Full operating system updater no

Is there a limitation which means this couldn’t be used to update the full operating system if the `.swu` is capable of this? I’m wondering about making a small wrapper for this around the demo at [GitHub - OE4T/tegra-demo-distro: Reference/demonstration distro for meta-tegra](https://github.com/OE4T/tegra-demo-distro?tab=readme-ov-file#update-image-demo) for Jetpack 5 and later mender support instead of the more complicated integration at [fix: Tegra, Jetpack 5: add Jetson as working target by mwest90 · Pull Request #19 · OE4T/meta-mender-community · GitHub](https://github.com/OE4T/meta-mender-community/pull/19)

---

<div class="post-metadata">

**Author:** ![TheYoctoJester](https://yyz2.discourse-cdn.com/flex036/user_avatar/hub.mender.io/theyoctojester/32/1444_2.png) [@TheYoctoJester](https://hub.mender.io/u/TheYoctoJester)\
**Post date:** [June 28, 2024, 8:45am UTC](https://hub.mender.io/t/swupdate/6953/3 "2024-06-28T08:45:22Z")

</div>

Hi @dwalkes,

Thanks for the heads up! The “full operating system updater: no” indicates that the flow of update-reboot-commit which involves SWUpdate along the way has not been tested. Technically it is certainly possible, but as root filesystem streaming is also not supported in this incarnation, I would not consider it a good strategy for new products.

The idea of this Update Module is being able to augment and retrofit existing products that are already using SWUpdate, for actively developed solutions I would not consider it a recommended choice.

Greets,  
Josef