Skip to content

Latest commit

 

History

History
255 lines (180 loc) · 12.8 KB

docs.md

File metadata and controls

255 lines (180 loc) · 12.8 KB
Raw
title taxonomy
Building a Mender Yocto Project image
category
docs

This document outlines the steps needed to build a Yocto Project image for a device. The build output will most notably include:

  • a disk image that can be flashed to the device storage during initial provisioning
  • an Artifact containing rootfs filesystem image file that Mender can deploy to your provisioned device, it has suffix .mender

!!! If you do not want to build your own images for testing purposes, the Getting started tutorials provide links to several demo images.

What is meta-mender?

meta-mender is a set of layers that enable the creation of a Yocto Project image where the Mender client is part of the image. With Mender installed and configured on the image, you can deploy image updates and benefit from features like automatic roll-back, remote management, logging and reporting.

Inside meta-mender there are several layers. The most important one is meta-mender-core, which is required by all builds that use Mender. meta-mender-core takes care of:

Each one of these steps can be configured further, see the linked sections for more details.

The other layers in meta-mender provide support for specific boards.

!!! For general information about getting started with Yocto Project, it is recommended to read the Yocto Project Quick Start guide.

Prerequisites

Board integrated with Mender

Mender needs to integrate with your board, most notably with the boot process. This integration enables robust and atomic rollbacks with Mender. Please see Device integration for general requirements and adjustment you might need to make before building.

Check out the board integrations at Mender Hub to see if your board is already integrated. If you encounter any issues and want to save time, you can use the Mender professional services to integrate your board.

Correct clock on device

Make sure that the clock is set correctly on your devices. Otherwise certificate verification will become unreliable and the Mender client can likely not connect to the Mender server. See certificate troubleshooting for more information.

Yocto Project

! We use the thud branch of the Yocto Project and thud branch of meta-mender below. Building meta-mender on other releases of the Yocto Project will likely not work seamlessly. meta-mender also has other branches like daisy that correspond to Yocto Project releases, but these branches are no longer maintained by Mender developers. We offer professional services to to implement and support other branches over time, please take a look at the Mender professional services offering.

A Yocto Project poky environment is required. If you already have this in your build environment, please open a terminal, go to the poky directory and skip to Adding the meta layers.

On the other hand, if you want to start from a clean Yocto Project environment, you need to clone the latest poky and go into the directory:

git clone -b thud git://git.yoctoproject.org/poky
cd poky

!!! Note that the Yocto Project also depends on some development tools to be in place.

Adding the meta layers

We will now add the required meta layers to our build environment. Please make sure you are standing in the directory where poky resides, i.e. the top level of the Yocto Project build tree, and run these commands:

git clone -b thud git://github.com/mendersoftware/meta-mender

Next, we initialize the build environment:

source oe-init-build-env

This creates a build directory with the default name, build, and makes it the current working directory.

We then need to add the Mender layers into our project:

bitbake-layers add-layer ../meta-mender/meta-mender-core

! The meta-mender-demo layer (below) is not appropriate if you are building for production devices. Please go to the section about building for production to see the difference between demo builds and production builds.

bitbake-layers add-layer ../meta-mender/meta-mender-demo

To simplify the board-specific integration, it is strongly recommended that you use the GRUB bootloader as an intermediate. See enabling GRUB for how to do this. Otherwise you need to add any Mender integration layer specific to your board; see Device integration for what is needed. For the three Mender reference devices use these layers (only add one of these):

  • Raspberry Pi 3 (other revisions might also work): bitbake-layers add-layer ../meta-mender/meta-mender-raspberrypi (depends on meta-raspberrypi)
  • BeagleBone Black: No board specific layer needed
  • Virtual boards: bitbake-layers add-layer ../meta-mender/meta-mender-qemu

!!! For board specific setup instructions please check out Mender Hub which contains our reference boards plus a large pool of community supported integrations

If you encounter any issues, please see Board integration for general requirements and adjustments you might need to enable your board to support Mender.

At this point, all the layers required for Mender should be part of your Yocto Project build environment.

Configuring the build

!!! The configuration in conf/local.conf below will create a build that runs the Mender client in managed mode, as a systemd service. It is also possible to run Mender standalone from the command-line or a custom script. See the section on customizations for steps to disable the systemd integration.

Add these lines to the start of your conf/local.conf:

# The name of the disk image and Artifact that will be built.
# This is what the device will report that it is running, and different updates must have different names
# because Mender will skip installation of an Artifact if it is already installed.
MENDER_ARTIFACT_NAME = "release-1"

INHERIT += "mender-full"

# A MACHINE integrated with Mender.
# raspberrypi3, beaglebone-yocto, vexpress-qemu and qemux86-64 are reference boards
MACHINE = "<YOUR-MACHINE>"

# The version of Mender to build. This needs to match an existing recipe in the meta-mender repository.
#
# Given your Yocto Project version, see which versions of Mender you can currently build here:
# https://docs.mender.io/architecture/compatibility#mender-client-and-yocto-project-version
#
# Given a Mender client version, see the corresponding version of the mender-artifact utility:
# https://docs.mender.io/architecture/compatibility#mender-clientserver-and-artifact-format
#
# Note that by default this will select the latest released version of the tools.
# If you need an earlier version, please uncomment the following and set to the
# required version.
#
# PREFERRED_VERSION_pn-mender = "1.1.%"
# PREFERRED_VERSION_pn-mender-artifact = "2.0.%"
# PREFERRED_VERSION_pn-mender-artifact-native = "2.0.%"

# The following settings to enable systemd are needed for all Yocto
# releases sumo and older.  Newer releases have these settings conditionally
# based on the MENDER_FEATURES settings and the inherit of mender-full above.
DISTRO_FEATURES_append = " systemd"
VIRTUAL-RUNTIME_init_manager = "systemd"
DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
VIRTUAL-RUNTIME_initscripts = ""

ARTIFACTIMG_FSTYPE = "ext4"

# Build for Hosted Mender
#
# To get your tenant token:
#    - log in to https://hosted.mender.io
#    - click your email at the top right and then "My organization"
#    - press the "COPY TO CLIPBOARD"
#    - assign content of clipboard to MENDER_TENANT_TOKEN
#
#MENDER_SERVER_URL = "https://hosted.mender.io"
#MENDER_TENANT_TOKEN = ""

# Build for Mender demo server
#
# https://docs.mender.io/getting-started/create-a-test-environment
#
# Uncomment below and update IP address to match the machine running the
# Mender demo server
#MENDER_DEMO_HOST_IP_ADDRESS = "192.168.0.100"

# Build for Mender production setup (on-prem)
#
# https://docs.mender.io/artifacts/building-for-production
#
# Uncomment below and update the URL to match your configured domain
# name and provide the path to the generated server.crt file.
#
# Note that a custom server.crt file is only necessary if you are using
# self-signed certificates.
#
# NOTE! It is recommend that you provide below information in your custom
# Yocto layer and this is only for demo purposes. See linked documentation
# for additional information.
#MENDER_SERVER_URL = "https://docker.mender.io"
#FILESEXTRAPATHS_prepend_pn-mender := "<DIRECTORY-CONTAINING-server.crt>:"
#SRC_URI_append_pn-mender = " file://server.crt"

!!! The size of the disk image (.sdimg) should match the total size of your storage so you do not leave unused space; see the variable MENDER_STORAGE_TOTAL_SIZE_MB for more information. Mender selects the file system type it builds into the disk image, which is used for initial flash provisioning, based on the ARTIFACTIMG_FSTYPE variable. See the section on file system types for more information.

!!! If you are building for Hosted Mender, make sure to set MENDER_SERVER_URL and MENDER_TENANT_TOKEN (see the comments above).

!!! If you would like to use a read-only root file system, please see the section on configuring the image for read-only rootfs.

Building the image

Once all the configuration steps are done, build an image with bitbake:

bitbake <YOUR-TARGET>

Replace <YOUR-TARGET> with the desired target or image name, e.g. core-image-full-cmdline.

!!! The first time you build a Yocto Project image, the build process can take several hours. The successive builds will only take a few minutes, so please be patient this first time.

Using the build output

After a successful build, the images and build artifacts are placed in tmp/deploy/images/<YOUR-MACHINE>/.

There is one Mender disk image, which will have one of the following suffixes:

  • .uefiimg if the system boots using the UEFI standard (x86 with UEFI or ARM with U-Boot and UEFI emulation) and GRUB bootloader
  • .sdimg if the system is an ARM system and boots using U-Boot (without UEFI emulation)
  • .biosimg if the system is an x86 system and boots using the traditional BIOS and GRUB bootloader

!!! Please consult the bootloader support section for information on which boot method is typically used in each build configuration.

This disk image is used to provision the device storage for devices without Mender running already. Please proceed to Provisioning a new device for steps to do this.

On the other hand, if you already have Mender running on your device and want to deploy a rootfs update using this build, you should use the Mender Artifact files, which have .mender suffix. You can either deploy this Artifact in managed mode with the Mender server as described in Deploy to physical devices or by using the Mender client only in Standalone deployments.

!!! If you built for one of the virtual Mender reference boards (qemux86-64 or vexpress-qemu), you can start up your newly built image with the script in ../meta-mender/meta-mender-qemu/scripts/mender-qemu and log in as root without password.