OrchestraOS Architecture¶

This chapter describes the current state of the OrchestraOS architecture, including versions of major software components, partition layout, and the boot process.

Versions of major software components¶

Major component versions¶
Component	Version	Reference / Notes
Yocto release	scarthgap	Long-term stable release (EOL: April 2028)
U-Boot	2024.04	MACHINE specific
Linux Kernel	6.6.52	MACHINE specific
BusyBox	1.36.1	SHA: 1a64f6a20aaf6ea4dbba68bbfa8cc1ab7e5c57c4
systemd	255.21	SHA: 70500d37992a01d3275b1c414c3ed161d691f9e9
Toolchain (aarch64-gcc)	13.4.0	SHA: 99677969d463d75a562f94460ea75e9f6a016b4f
KAS container (build environment)	5.0	Image: 5.0-debian-bookworm

Partition layout¶

The OrchestraOS LVM layout is selected by orcos-lvm-layout.inc. Two WIC templates are available:

wic/orcos-reference-layout-lvm-initramfs.wks.in: rootfs-on-LVM layout. This is the default when RAUC is enabled and ORCOS_ROOTFS_ON_LVM is true.
wic/orcos-reference-layout-lvm.wks.in: non-initramfs LVM layout. In this layout the rootfs slots remain physical partitions and only application and persistent data storage are placed in LVM.

In both layouts the LVM physical volume can optionally be encrypted by adding the meta-orchestraos-crypt layer. When encryption is enabled, all logical volumes inside the LVM physical volume inherit that protection.

Layout comparison¶
Aspect	Rootfs on LVM	Rootfs on physical partitions
WIC template	`wic/orcos-reference-layout-lvm-initramfs.wks.in`	`wic/orcos-reference-layout-lvm.wks.in`
Root filesystem slots	`rootfs_A` and `rootfs_B` are LVM logical volumes.	`rootfs_A` and `rootfs_B` are physical ext4 partitions.
Boot filesystem slots	`boot_A` and `boot_B` are physical ext4 partitions.	Boot files are part of the rootfs physical partitions.
LVM contents	`rootfs_A`, `rootfs_B`, `app_A`, `app_B`, and `data`.	`app_A`, `app_B`, and `data`.
Boot-time behavior	Initramfs creates or activates `vg_lvm` and mounts the selected rootfs logical volume.	The kernel mounts the selected rootfs physical partition directly; LVM is activated later for application and data storage.
`/etc` persistence	`overlayfs-etc` is enabled and stores the writable `/etc` upper layer on `/data`.	`overlayfs-etc` is not enabled by the reference image policy for this layout.
Optional encryption scope	The LVM PV can protect rootfs, application, and persistent data logical volumes.	The LVM PV can protect application and persistent data logical volumes; rootfs physical partitions remain outside LVM.

For the rootfs-on-LVM layout, orchestraos-image-minimal adds the overlayfs-etc image feature when ORCOS_ROOTFS_ON_LVM is true. The overlay mount point is /data, the filesystem type is ext4, and the backing device is /dev/mapper/${VG_LVM_LABEL}-${DATA_PART_LABEL}. This keeps the rootfs read-only while allowing controlled persistence for /etc.

Physical partition order¶
Area	Rootfs on LVM	Rootfs on physical partitions
eMMC boot areas	`uboot_A` in `mmcblkXboot0` and `uboot_B` in `mmcblkXboot1`.	`uboot_A` in `mmcblkXboot0` and `uboot_B` in `mmcblkXboot1`.
eMMC RPMB	RPMB area is reserved and not used by the WIC image.	RPMB area is reserved and not used by the WIC image.
Partition 1	`data-unencrypted`: ext4, `UNENCRYPTED_PART_SIZE` default 32 MiB.	`data-unencrypted`: ext4, `UNENCRYPTED_PART_SIZE` default 32 MiB.
Partition 2	`boot_A`: ext4, `BOOT_PART_SIZE`.	`rootfs_A`: ext4, `ROOTFS_PART_SIZE`.
Partition 3	`boot_B`: ext4, `BOOT_PART_SIZE`.	`rootfs_B`: ext4, `ROOTFS_PART_SIZE`.
Partition 4	`lvm`: LVM physical volume, `LVM_PART_SIZE` default 4096 MiB.	`lvm`: LVM physical volume, `LVM_PART_SIZE` default 4096 MiB.

LVM logical volumes¶
Logical volume	Rootfs on LVM	Rootfs on physical partitions	Updatable	File system
`rootfs_A`	Present, size `ROOTFS_PART_SIZE`.	Not present in LVM.	Yes	ext4
`rootfs_B`	Present, size `ROOTFS_PART_SIZE`.	Not present in LVM.	Yes	ext4
`app_A`	Present, size `APP_PART_SIZE`.	Present, size `APP_PART_SIZE`.	Yes	ext4
`app_B`	Present, size `APP_PART_SIZE`.	Present, size `APP_PART_SIZE`.	Yes	ext4
`data`	Present, uses remaining free LVM space.	Present, uses remaining free LVM space.	No	ext4

Note

LVM encryption is optional and applies to the complete LVM physical volume, not to individual logical volumes. The exact encryption backend is provided by the selected BSP/security integration, for example NXP CAAM on supported NXP targets.

Initramfs LVM policy hooks¶

The initramfs-module-lvm-grow and initramfs-module-lvm-create packages own partition growth, LVM creation, filesystem initialization, and the completion marker. Optional packages can add policy files without replacing these packages, their files, or their shell functions.

initramfs-framework-orchestra advertises LVM_HOOKS_API = "1". LVM_HOOKS_DIR defaults to /etc/lvm-hooks.d. Files in each event directory are sourced in filename order in the initramfs shell:

LVM policy events¶
Event	When it runs	Policy control
`before-grow`	After detecting a misplaced GPT backup header, before changing the disk	Abort if growth is unsafe
`before-create`	Before inspecting or initializing the configured LVM device	Validate storage; optionally set `LVM_CREATE_WIPE_SIGNATURES=0`
`before-cleanup`	Before destructive LVM cleanup, including failure recovery	Set `LVM_CLEANUP_ALLOWED=0` to preserve storage

The two policy flags default to 1 for each operation. With no hook files, signature removal and cleanup retain their existing behavior. Existing volume groups with .lvm_created.done continue to skip initialization. No disk format, volume name, or completion-marker path changes are required. If the completion marker exists but the volume group cannot be read, boot stops for recovery instead of attempting to initialize storage again.

Hooks must explicitly check command failures and call lvm_fail when an operation must not continue. Returning a nonzero status from a sourced hook also aborts boot. lvm_fail exits even if fatal returns, preventing the failed operation from continuing. Hooks share shell state, so use a feature-specific prefix for their own variables and functions.

For example, an optional encryption policy package can install:

# /etc/lvm-hooks.d/before-cleanup/10-encryption
LVM_CLEANUP_ALLOWED=0

The base modules still perform the LVM operations. They handle command failures explicitly and flush initialized storage before persisting the completion marker. Encryption packages remain responsible for loading keys, creating the mapped device before 08-lvm_create, and supplying any encryption-specific guards.

For instructions on including optional test packages in an image, see Optional target tests.

RAUC Update Flow¶

RAUC support is enabled by adding rauc to DISTRO_FEATURES. The orchestraos-image-minimal recipe then includes orchestraos-image-rauc.inc, which selects the RAUC-aware WIC layout and pulls in the RAUC configuration from meta-orchestraos-rauc.

The OrchestraOS RAUC bundle format is verity. The default bundle contains:

RAUC bundle slots¶
Slot	Artifact	Purpose
`bootloader`	Machine bootloader image	Updates the boot container or U-Boot image used by the target.
`boot`	`boot.ext4`	Present when the initramfs/rootfs-on-LVM layout is used; updates the selected boot filesystem slot.
`rootfs`	`rootfs.ext4`	Updates the selected root filesystem slot.
`app`	`appfs.ext4`	Updates the selected application filesystem slot.

For i.MX targets, meta-orchestraos-rauc derives the bootloader artifact name from the selected machine, bootloader configuration, and signing state. If secure boot signing is enabled, the RAUC bootloader slot uses the signed bootloader artifact.

RAUC system configuration is generated from templates. With INITRAMFS_IMAGE_BUNDLE enabled, rootfs slots point to /dev/mapper/${VG_LVM_LABEL}-${ROOTFS_SLOT_*_LABEL}; otherwise, rootfs slots point to physical eMMC partitions. Application slots point to LVM logical volumes in both layouts. The RAUC data directory defaults to /data.

The image also installs the RAUC service, rauc-hawkbit-updater, OrchestraOS hawkBit updater configuration, and a hawkBit version reporter. Development signing keys and certificates are provided by meta-orchestraos-rauc for reference images; production deployments must replace them.

Booting process (NXP targets)¶

For NXP targets, the boot flow follows NXP secure boot (HAB) guidance and may use OP-TEE and ARM Trusted Firmware to enforce a secure chain of trust.

The diagram below illustrates a high-level secure boot overview:

        Host PC + CST                             i.MX + HAB
        +----------+                             +----------+
   ---> |  U-Boot  |                             | Compare  |
   |    +----------+                             +----------+
   |          |                                     ^    ^
   |          v                         Reference  /      \  Generated
   |    +----------+                      Hash    /        \   Hash
   |    |   Hash   |  Private                    /          \
   |    +----------+    Key                     /            \
   |          |          |                +----------+  +----------+
   |          v          |                |  Verify  |  |   Hash   |
   |    +----------+     |                +----------+  +----------+
   |    |   Sign   |  <---      SRK            ^            ^
   |    +----------+            HASH            \          /
   |          |                  |          CSF  \        /   U-Boot
   |          v                  v                \      /
   |    +----------+        +----------+        +----------+
   |    |  U-Boot  |        |          |        |  U-Boot  |
   ---> |     +    | -----> |   i.MX   | -----> |     +    |
        |    CSF   |        |          |        |    CSF   |
        +----------+        +----------+        +----------+

The high level description of the chain of trust execution is as follows:

ROM root of trust: On reset, the i.MX Boot ROM enforces secure boot and will only start an authenticated bootloader (U-Boot).
Fused trust anchor (SRK hash): A PKI is generated offline; the SRK hash is fused into the SoC to anchor trust and allow revocation (up to 3 of 4 keys).
Signed boot image (CSF): U-Boot is packaged with a CSF that contains the data iMX security module needs (SRK table/certs/signatures) to verify it.
Authentication at boot: the chip validates the CSF/SRK table against the fused SRK hash and verifies signatures; failures block boot.
Chain of trust to Linux: After U-Boot is trusted, it can verify the Linux kernel (and optionally DTB/initramfs) using keys anchored to the same trust root.
Optional encrypted boot (CAAM): U-Boot can be encrypted (AES-CCM) for confidentiality; the per-device DEK is protected in a CAAM blob (OTPMK/PRIBLOB) to prevent reuse/tampering.
Result: Only authorized (and optionally encrypted) boot and kernel components are allowed to execute

The official NXP documentation describing the boot process can be found here. More detailed guides, including OP-TEE, ARM Trusted Firmware, and Secure/Non-secure world transitions, are available in the NXP documentation.

Boot flows may differ between SoC families (e.g. i.MX8M vs i.MX6 vs i.MX93). For supported hardware targets in OrchestraOS, see Supported Hardware.

File system contents¶

/data – persistent data that is not replaced during over-the-air updates. It may be encrypted or unencrypted depending on OS configuration. By default it is used to store Docker data, configuration, and other persistent state. The specific usage is flexible, with the general assumption that writes should be controlled to reduce flash wear.
/data/orchestrad – files required for OrchestraD operation, including the CA certificate and configuration.
/data/docker – Docker images, containers, volumes, and related state.
/data/rauc – is used for rauc related software update procedure.
/home/<user> – by default the user is ct; the home directory contains standard shell files such as .bashrc and .profile.

Docker runtime policy¶

OrchestraOS uses docker-moby as the Docker provider and installs docker-compose in the base image. The Docker service is enabled by default through a systemd wants symlink.

Docker runtime state is intentionally moved out of the root filesystem:

Docker daemon data root is configured as /data/docker.
/root/.docker is a symlink to /data/.docker.
The daemon configuration is installed as /etc/docker/daemon.json.

The Docker daemon configuration is selected at build time from the Docker recipe version. Docker 24.0 and newer use the current configuration, while older Docker versions also keep the legacy key path setting required by older Moby releases. Because Docker state lives under /data, it is preserved across rootfs updates and follows the encryption policy of the data LVM volume when encrypted storage is enabled.

System users and groups¶

By default, OrchestraOS includes two users:

ct – the default user with sudo access. If local login is enabled, it uses the default password cthingsco.

The ct user is a member of the following groups by default:

tty
disk
uucp
sudo
audio
video
plugdev
kvm
wheel
docker
ct

Ports and network configuration¶

Default listening ports in OrchestraOS:

Open ports configuration¶
Description	Protocol	Local Address	Foreign Address
init	tcp	0.0.0.0:111	0.0.0.0:*
dnsmasq	tcp	0.0.0.0:53	0.0.0.0:*
sshd (if enabled)	tcp	0.0.0.0:22	0.0.0.0:*
containerd	tcp	127.0.0.1:<various>	0.0.0.0:*
init	tcp6	:::111	:::*
dnsmasq	tcp6	:::53	:::*
sshd (if enabled)	tcp6	:::22	:::*

By default, NetworkManager is configured with DHCP and iwd. If ModemManager is enabled, the default cellular connection profile is:

[connection]
id=cellular
type=gsm

[gsm]
apn=cthingsco

[ipv4]
method=auto

[ipv6]
addr-gen-mode=default
method=auto

[proxy]