Linux microPlatform Over-the-Air Updates¶
What is an Over-the-Air Update System?¶
Over-the-air (OTA) update systems provide a secure means of updating a device remotely. The Linux microPlatform has choosen to support a framework based on on the TUF/Uptane specifications. This is implemented by using root file systems managed with OSTree and the Aktualizr open source project.
This page describes OTA updates using the following framework implementations:
- The Linux microPlatform subscriber demo server
- ATS Garage’s system
Gotchas¶
Both the subscriber demo server (which is based on OTA Community Edition) and ATS Garage have a few caveats you should be aware of:
- After the initial registration, the device’s image “name” will appear to be unknown. Looking closely, you’ll see its hash matches that of a known image. This is a known peculiarity and the image name will be correct after the first update is applied.
- “Updating” a device only installs the image. It does not make that image active. A reboot is required for the image to become active, and that policy is up to the user to define.
- If you enable auto-updates and aren’t on the latest image, nothing will happen until a new image is released. Any updates before that time must be performed manually.
Updating Your Linux microPlatform Device¶
Choose a method:
- Foundries.io Subscriber Demo Server
- ATS Garage
Linux microPlatform subscribers have the easiest path to experimenting with OTAs. Subscribers have access to a device management interface for up to 5 devices. The Linux microPlatform image includes a program to register the device with the foundries.io OTA community edition server. Registering the device is as simple as:
sudo lmp-device-register -n <name of your device as it should appear in UI>
# Follow the instructions which appear in the terminal.
# systemd will eventually restart aktualizr and the device will register.
# To make it happen immediately run:
sudo systemctl restart aktualizr
Once registered, the device will show up under https://app.foundries.io/devices/ and you’ll have the ability to start managing updates from there.
Debugging OTA Issues¶
The aktualizr logs are the best place to look for when trying to debug an issue. The logs are managed via systemd, so they can be tailed with:
sudo journalctl -f -u aktualizr
The default logging level used by aktualizr is “2”. This can be lowered to increase its verbosity by creating a file like:
# /etc/sota/sota.env
AKTUALIZR_CMDLINE_PARAMETERS=--config /var/sota/sota.toml --loglevel 1
Changes to this file won’t be picked up by Aktualizr until it’s restarted.
Another place to look for information is from the ostree
program that’s
installed on the device. You can find out which image is active and which
image will become active by running:
$ ostree admin status
lmp a624daeebc085381493ba9745a983e9c1f792751f99d75fd026fbc6eedcdc8c5.1 (pending)
origin refspec: a624daeebc085381493ba9745a983e9c1f792751f99d75fd026fbc6eedcdc8c5
* lmp 493b9c454b732ee221a015c6f4ce6bb5c3c5d767111bae94cc3b93aa9c89b64e.0
origin refspec: 493b9c454b732ee221a015c6f4ce6bb5c3c5d767111bae94cc3b93aa9c89b64e
The output means that the active image on the device is 493b...
,
and the a624...
image is pending. That is, an update has been
successfully downloaded and applied to OSTree, but the device has not
yet been rebooted so that the image can become active.
Automatic Rebooting After Updates¶
Aktualizr creates an empty file /var/run/aktualizr-session/need_reboot
after
completing an OSTree update, and a systemd timer can be defined for the systemd
service file ostree-pending-reboot
to automatically restart the device once
there is a pending update.
To create a systemd timer that activates the ostree-pending-reboot
service every day at 5:00 AM UTC, create a file named
/etc/systemd/system/ostree-pending-reboot.timer
with the following
contents:
[Unit]
Description=Automatic OSTree Update Reboot Scheduling
[Timer]
OnCalendar=*-*-* 05:00:00
[Install]
WantedBy=multi-user.target
Then enable and start the timer by running:
sudo systemctl enable ostree-pending-reboot.timer
sudo systemctl start ostree-pending-reboot.timer