.. _os-architecture: ######################## 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 ===================================== .. list-table:: Major component versions :header-rows: 1 * - 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. .. list-table:: Layout comparison :header-rows: 1 * - 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``. .. list-table:: Physical partition order :header-rows: 1 * - 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. .. list-table:: LVM logical volumes :header-rows: 1 * - 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. 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: .. list-table:: RAUC bundle slots :header-rows: 1 * - 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. .. _os-booting-process-nxp: 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. .. code-block:: text 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 :ref:`os-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/`` – 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: .. list-table:: Open ports configuration :header-rows: 1 * - 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: - 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: .. code-block:: text [connection] id=cellular type=gsm [gsm] apn=cthingsco [ipv4] method=auto [ipv6] addr-gen-mode=default method=auto [proxy]