Home

Awesome

Balena.io layers for Yocto

Description

This repository enables building balenaOS for various devices.

Layers Structure

Dependencies

Versioning

The meta-balena version is kept in the DISTRO_VERSION variable. The balena-<board> version is kept in the file called VERSION located in the root of the balena-<board> repository and read in the build as the variable HOSTOS_VERSION.

We define host OS version as the balena-<board> version and we use this version as HOSTOS_VERSION.

Build flags

Before bitbake-ing with meta-balena support, a few flags can be changed in the conf/local.conf from the build directory. Editing of local.conf is to be done after source-ing. See below for explanation on such build flags.

Configure custom network manager

By default balena uses NetworkManager on host OS to provide connectivity. If you want to change and use other providers, list your packages using NETWORK_MANAGER_PACKAGES. You can add this variable to local.conf. Here is an example:

NETWORK_MANAGER_PACKAGES = "mynetworkmanager mynetworkmanager-client"

Customizing splash

We configure all of our initial images to produce a balena logo at boot, shutdown or reboot. But we encourage any user to go and replace that logo with their own. All you have to do is replace the splash/balena-logo.png file that you will find in the first partition of our images (boot partition) with your own image. NOTE: As it currently stands plymouth expects the image to be named balena-logo.png. In older releases this file was called resin-logo.png.

Docker storage driver

By default the build system will set all the bits needed for the docker to be able to use the aufs storage driver. This can be changed by defining BALENA_STORAGE in your local.conf. It supports aufs and overlay2.

OS development

To configure a development build that disables quiet boot and allows bootloader shell access, edit the build's local.conf adding:

OS_DEVELOPMENT = "1"

This is a development only setting and no OS_DEVELOPMENT configured images are deployed.

The OS

SSH and Avahi services

The OS runs SSH (openSSH) on port 22222. Running this service takes advantage of the socket activation systemd feature so the SSH daemon will only run when there is a SSH connection to the device saving idle resources in this way. In order to connect to a device, one can use it's IP when known or resolve the hostname over mDNS as its hostname is advertised over network using an avahi service. When the latter is used, configuration of the client is needed (see for example https://wiki.archlinux.org/index.php/Avahi#Hostname_resolution).

Time synchronization

At boot, time is set and synchronized as follows:

Build time

Initially time is set from the image build time timestamp, stored in /etc/timestamp and generated by the build system when the image is generated.

Previous boot system time

The system then checks whether the previous boot system time was stored in persistent storage and uses it to correct the time. Time is stored in persistent storage on an hourly timer and on system reboot or shutdown. Logging starts after the last boot system time is set.

RTC time

When an RTC is available (/dev/rtc), a timeinit-rtc service is started that updates the system clock using the value read from the RTC. If there is no RTC available, the service will not do anything.

HTTPs time

After a network connectivity event, an HTTPs time synchronization service timesync-https, is then used to correct the time from HTTP headers timestamps, assuming the correct system time has not been set from the RTC previously. This guarantees the time is broadly correct and certificates expiration checks won't fail. Other network services are held until this time synchronization happens. By default, the time synchronization uses the NetworkManager connectivity URL defined in the connectivity section of config.json. To disable the HTTPs time sync and allow other services to run, set the connectivity check URI to 'null'. This will also disable connectivity checks too.

Network time

The chronyd services is responsible of managing the time afterwards using NTP. It is configured to synchronize every 4h approximately to save bandwidth. If the NTP servers become unreachable, the service will continuously try to update the time. If the time gets unsynchronized, the NTP client service will be restarted to correct failures.

The time keeping framework explained above provides robust time initialization and management both when RTC is available and when not.

Bootloader

The bootloader needs to select the active root filesystem, load, and launch the Linux kernel. It also manages boot counts and rollbacks. BalenaOS supports several bootloaders across the supported devices line-up.

Rollback framework

Check docs/rollbacks.md for the rollback documentation

Devices support

WiFi Adapters

We currently tested and provide explicit support for the following WiFi adapters:

Modems

We currently test as part of our release process and provide explicit support for the following modems:

Recommended WiFi USB dongle

How to fix various build errors

Step 3 : RUN chmod 700 /entry.sh
---> Running in 445fe69866f9
operation not supported

This is probably because of a docker bug where, if you update kernel and don't reboot, docker gets confused. The fix is to reboot your system. More info: http://stackoverflow.com/questions/29546388/getting-an-operation-not-supported-error-when-trying-to-run-something-while-bu

config.json

The behavior of balenaOS can be configured by setting the following keys in the config.json file in the boot partition. This configuration file is also used by the supervisor.

hostname

(string) The configured hostname of the device, otherwise the device UUID is used.

persistentLogging

(boolean) Enable or disable persistent logging on the device - defaults to false. Once persistent journals are enabled, they end up stored as part of the data partition on the device (either on SD card, eMMC, harddisk, etc.). This is located on-device at /var/log/journal/<uuid> where the UUID is variable.

country

(string) Two-letter country code for the country in which the device is operating. This is used for setting the WiFi regulatory domain, and you should check the WiFi device driver for a list of supported country codes.

ntpServers

(string) A space-separated list of NTP servers to use for time synchronization. Defaults to resinio.pool.ntp.org servers:

dnsServers

(string) A space-separated list of preferred DNS servers to use for name resolution.

balenaRootCA

(string) A base64-encoded PEM CA certificate that will be installed into the root trust store. This makes the device trust TLS/SSL certificates from this authority. This is useful when the device is running behind a re-encrypting network device, like a transparent proxy or some deep packet inspection devices.

"balenaRootCA": "4oCU4oCTQkVHSU4gQ0VSVElGSUNBVEXigJTi..."

developmentMode

To enable development mode at runtime:

"developmentMode": true

By default development mode enables unauthenticated SSH logins unless custom SSH keys are present, in which case SSH key access is enforced.

Also, development mode provides serial console passwordless login as well as an exposed balena engine socket to use in local mode development.

os

An object containing settings that customize the host OS at runtime.

network

wifi

An object that defines the configuration related to Wi-Fi.

The following example disables MAC address randomization of Wi-Fi device during scanning:

"os": {
 "network" : {
  "wifi": {
    "randomMacAddressScan": false
  }
 }
}
connectivity

An object that defines configuration related to networking connectivity checks. This feature builds on NetworkManager's connectivity check, which is further documented in the connectivity section here.

The following example configures the connectivity check by passing the balenaCloud connectivity endpoint with a 5-minute interval.

"os": {
 "network" : {
  "connectivity": {
    "uri" : "https://api.balena-cloud.com/connectivity-check",
    "interval" : "300"
  }
 }
}

udevRules

An object containing one or more custom udev rules as key:value pairs.

To turn a rule into a format that can be easily added to config.json, use the following command:

cat rulefilename | jq -sR .

For example:

root@resin:/etc/udev/rules.d# cat 64.rules | jq -sR .
"ACTION!=\"add|change\", GOTO=\"modeswitch_rules_end\"\nKERNEL==\"ttyACM*\", ATTRS{idVendor}==\"1546\", ATTRS{idProduct}==\"1146\", TAG+=\"systemd\", ENV{SYSTEMD_WANTS}=\"u-blox-switch@'%E{DEVNAME}'.service\"\nLBEL=\"modeswitch_rules_end\"\n"

The following example contains two custom udev rules that will create /etc/udev/rules.d/56.rules and /etc/udev/rules.d/64.rules. The first time rules are added, or when they are modified, udevd will reload the rules and re-trigger.

"os": {
 "udevRules": {
  "56": "ENV{ID_FS_LABEL_ENC}==\"resin-root*\", IMPORT{program}=\"resin_update_state_probe $devnode\", SYMLINK+=\"disk/by-state/$env{BALENA_UPDATE_STATE}\"",
  "64" : "ACTION!=\"add|change\", GOTO=\"modeswitch_rules_end\"\nKERNEL==\"ttyACM*\", ATTRS{idVendor}==\"1546\", ATTRS{idProduct}==\"1146\", TAG+=\"systemd\", ENV{SYSTEMD_WANTS}=\"u-blox-switch@'%E{DEVNAME}'.service\"\nLBEL=\"modeswitch_rules_end\"\n"
 }
}

sshKeys

(Array) An array of strings containing a list of public SSH keys that will be used by the SSH server for authentication.

"os": {
 "sshKeys": [
  "ssh-rsa AAAAB3Nza...M2JB balena@macbook-pro",
  "ssh-rsa AAAAB3Nza...nFTQ balena@zenbook"
 ]
}

fan

An object that defines thermal related configuration. Available for Jetson Orin devices running Jetpack 6 or newer, balenaOS v6.1.24 or newer and Supervisor v16.10.0 or newer.

fan.profile

(string) A string which will be used to select the desired cooling profile. Supported values are "quiet" and "cool". At runtime, this configuration option should be set through the API or from your balenaCloud dashboard.

"os": {
 "fan": {
  "profile":"cool"
 }
}

power

An object that defines power consumption related configuration. Available for Jetson Orin devices running Jetpack 6 or newer, balenaOS v6.1.24 or newer and Supervisor v16.10.0 or newer.

power.mode

(string) A string which will be used to select the desired power mode. Supported values for Jetpack 6 and newer are "low", "mid" and "high", where "low" is the lowest power consumption mode while "high" corresponds to MAXN or the highest available power mode for your device type. At runtime, this configuration option should be set through the API or from your balenaCloud dashboard, and it will cause a device reboot.

"os": {
 "power": {
  "mode":"high"
 }
}

installer

An object that configures the behaviour of the balenaOS installer image.

secureboot

(boolean) Opt-in to installing a secure boot and encrypted disk system for supported device types.

"installer": {
  "secureboot": true
}

migrate

An object that configures the behaviour of the balenaOS installer migration module.

migrate.force

(boolean) Forces the migration to run. By default the migration only runs if the installer is booting in a single disk system or the migrate argument is passed in the kernel command line.

"installer": {
  "migrate": {
    "force": true
  }
}

target_devices

(string) Overrides the default list of provisioning target mediums. May contain one or more devices, separated by spaces. The first one found will be used.

"installer": {
  "target_devices":"nvme0n1 sda"
}

Yocto version support

The following Yocto versions are supported: