README
¶
Mender
Mender is a framework for automating over-the-air software updates to Linux-based embedded devices.
In order to test it, it is strongly recommended to build it as a part of a Yocto image, as you will need to have the bootloader and partition layout set up in a specific way. Yocto layers are provided in the meta-mender repository.
- How it works ===============
Mender performs a full image update of the embedded device. Currently, both the kernel and rootfs are expected to be part of the image update. Updating the bootloader is considered less important and more risky, so the first version of Mender is not designed to update the bootloader.
- Partitioning target device =============================
At least three different partitions are required, one of which is the boot partition, and the remaining two partitions are where both the kernel and rootfs are stored. One of the partitions will be used as active partition, from which the kernel and rootfs will be booted, the second one will be used by the update mechanism to write the updated image. The second partition will be referred to as "inactive" later in this document.
It is also possible to use yet another partition to store persistent user data, so this does not get overwritten during an update.
A sample partition layout is shown below:
+--------+
| EEPROM |
+--------+
+----------------------+
| boot partition (FAT) |
+----------------------+
+-----------+-----------+
| rootfs | rootfs |
| kernel | kernel |
+-----------+-----------+
+------------+
| user data |
| (optional) |
+------------+
- Bootloader support =====================
Mender is currently designed to be used with the U-Boot bootloader. The choice of U-Boot was made based on its flexibility and popularity in embedded devices. It is also open source, which enables any required modifications or adjustments.
Besides any special configuration to support the device, U-Boot needs to be compiled and used with a feature known as as Boot Count Limit. It enables specific actions to be triggered when the boot process fails a certain amount of attempts.
Support for modifying U-Boot variables from userspace is also required so that fw_printenv/fw_setenv utilities are available in userspace. These utilities can be compiled from U-Boot sources and are part of U-Boot.
- Boot process ===============
TBD
- Testing Mender with Yocto and QEMU =====================================
To quickly get started, Mender can be tested using the QEMU emulator. Detailed instructions how to build a Yocto image that can be run and tested in QEMU are provided in the meta-mender repository.
- Running Mender =================
Please note that the process described here is mostly manual as the development of both the client and server component is still in progress. It will be fully automated in the future, including the ability to of automatically roll back when update process fails.
What is more, as Mender is not a stand-alone application, but needs integration with the bootloader and requires certain partitioning schema, it is recommended to use it with the provided Yocto Mender layers for a self-containing image build. It is however possible to use it independently by setting up the needed dependencies and requirements.
Assuming that all the dependencies are resolved, in order to use Mender you need to run:
$ mender -rootfs image
where image is a complete image containing the kernel and rootfs. This command will install the image on the inactive
partition and set the needed U-Boot variables so that after a restart, the system will be booted from the inactive partition
and use the freshly updated kernel and rootfs.
Please note that image can be a http URL or be manually copied to the local file device system, but in the future this will be
done automatically and will be an event-driven process. The Mender client will communicate with the server in
order to get notifications when a new update is scheduled and then fetch the image that will be used to update
device.
6A. Successful update
After fetching a new image, installing using mender -rootfs image, reboot and (currently manual) verification that the new image is working correctly you need to commit
changes and inform Mender that the new image is running correctly. In order to do so run:
$ mender -commit
This will set all the required boot configurations so that after device will be restarted again it will be booted from the updated partition and thus the inactive partition will become new active partition. The process can then be repeated so that a new image will be installed to the new inactive partition which then can be tested and verified.
6B. Failing update
If for some reason the new image is broken, or userspace verification is failing, the device will be rolled back to the previously working image. This is possible by having two kernel and rootfs partitions, as you can always have one version of the kernel and rootfs which is verified to work correctly and one which is used to write the update.
In order to simulate this behavior after performing the update with mender -rootfs image and rebooting device, simply
don't run the mender -commit command. This will cause boot variables to not be updated and after the next reboot, the
device will be booted from the active partition (not updated one) instead.
6C. Automatic roll-back
Also if for some reason U-Boot will detect that the newly updated image can not be booted after a defined number of tries
(this can be configured by setting bootlimit U-Boot variable), the device will be switched to roll-back mode
and the partition with the update won't be used to boot. Instead, the active partition will be used as it has been proven
to work correctly.
- Project roadmap ==================
As mentioned, the update process mostly consists of manual steps at the moment. There is ongoing work to make it fully automated so that the image will be delivered to device automatically and the whole update and roll-back process will be automatic. There is also ongoing work on the server side of the update framework, where you will be able to schedule image updates and get the reports for the update status for each and every device connected to the server.
Documentation
¶
Overview ¶
Copyright 2016 Mender Software AS
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Copyright 2016 Mender Software AS
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Copyright 2016 Mender Software AS
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Copyright 2016 Mender Software AS
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Copyright 2016 Mender Software AS
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Copyright 2016 Mender Software AS
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Copyright 2016 Mender Software AS
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Copyright 2016 Mender Software AS
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Copyright 2016 Mender Software AS
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Copyright 2016 Mender Software AS
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Copyright 2016 Mender Software AS
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Godeps
|
|
|
_workspace/src/github.com/Sirupsen/logrus
Package logrus is a structured logger for Go, completely API compatible with the standard library logger.
|
Package logrus is a structured logger for Go, completely API compatible with the standard library logger. |
|
_workspace/src/github.com/davecgh/go-spew/spew
Package spew implements a deep pretty printer for Go data structures to aid in debugging.
|
Package spew implements a deep pretty printer for Go data structures to aid in debugging. |
|
_workspace/src/github.com/pmezard/go-difflib/difflib
Package difflib is a partial port of Python difflib module.
|
Package difflib is a partial port of Python difflib module. |
|
_workspace/src/github.com/stretchr/testify/assert
Package assert provides a set of comprehensive testing tools for use with the normal Go testing system.
|
Package assert provides a set of comprehensive testing tools for use with the normal Go testing system. |
|
_workspace/src/golang.org/x/sys/unix
Package unix contains an interface to the low-level operating system primitives.
|
Package unix contains an interface to the low-level operating system primitives. |