.. _os-architecture-storage: ########################## Storage and System Updates ########################## The reference layout pairs boot, operating-system, and application slots for image-based updates. A shared data filesystem keeps configuration and runtime state across those slot changes. .. _os-partition-layout: Partition Layout ================ .. figure:: images/orchestraos-storage.svg :alt: EIG hardware boot areas contain bootloader copies. User-area partitions hold provisioning state, boot slots A and B, and LVM volumes for rootfs A and B, application A and B, and shared persistent data. Encryption of LVM is optional. :width: 100% :class: architecture-figure Reference rootfs-on-LVM layout. EIG eMMC boot areas are outside the WIC user-area partition table; virtual disks have no eMMC hardware boot areas. Optional encrypted storage protects the LVM region. ``orcos-lvm-layout.inc`` supplies common LVM policy. With RAUC selected, ``orchestraos-image-rauc.inc`` chooses a WIC template from the rootfs setting and bootloader backend: .. list-table:: Layout selection :header-rows: 1 * - Configuration - WIC template - Rootfs and boot slots * - Rootfs on LVM, U-Boot - ``orcos-reference-layout-lvm-initramfs.wks.in`` - LVM rootfs A/B; physical ext4 boot A/B. * - Rootfs on LVM, EFI - ``orcos-reference-layout-lvm-initramfs-efi.wks.in`` - LVM rootfs A/B; physical FAT boot A/B, both EFI system partitions. * - Rootfs on physical partitions - ``orcos-reference-layout-lvm.wks.in`` - Physical ext4 rootfs A/B containing the boot files. LVM holds application A/B and data. ``ORCOS_ROOTFS_ON_LVM`` defaults to ``1`` in the common distribution policy. Initramfs creates or activates the volume group before mounting an LVM rootfs. In the physical-rootfs layout, storage services activate application/data LVM later. The crypt layer requires rootfs on LVM and does not support the physical-rootfs layout; see :ref:`os-extended-security`. The four physical partitions are: .. list-table:: Physical partition order :header-rows: 1 * - Partition - Rootfs-on-LVM layout - Physical-rootfs layout * - 1 - ``data-unencrypted``, ext4. - ``data-unencrypted``, ext4. * - 2 - ``boot_A``, ext4 or FAT according to the backend. - ``rootfs_A``, ext4. * - 3 - ``boot_B``, ext4 or FAT according to the backend. - ``rootfs_B``, ext4. * - 4 - LVM physical volume for rootfs A/B, app A/B, and data. - LVM physical volume for app A/B and data. On EIG hardware, the two eMMC hardware boot areas contain the redundant bootloader copies. They are outside the user-area WIC partition table. RPMB is also outside that table and is not populated by these WIC templates. QEMU's firmware is supplied separately; its virtual disk has no eMMC boot areas. .. list-table:: Logical volumes :header-rows: 1 * - Volume - Size policy - Update behavior * - ``rootfs_A``, ``rootfs_B`` - ``ROOTFS_PART_SIZE`` each; present only with rootfs on LVM. - Written as part of the selected RAUC slot group. * - ``app_A``, ``app_B`` - ``APP_PART_SIZE`` each. - Written as part of the selected RAUC slot group. * - ``data`` - Remaining free volume-group extents. - Persistent; not a payload slot in the reference RAUC bundle. Disk Naming ----------- The disk is described by ``ORCOS_DISK_DEVICE_NAME`` and ``ORCOS_DISK_PART_PREFIX``. EIG defaults derive from ``EMMC_DEV`` and use the ``p`` separator, for example ``/dev/mmcblk2p4``. QEMU sets the disk name to ``vda`` and the separator to the empty string, producing ``/dev/vda4``. ``ORCOS_DISK_DEVICE``, ``ORCOS_DISK_PART``, and the configured partition indices are then used by provisioning, mount, and RAUC templates. Changing disk naming is a platform integration decision: disk layout, firmware boot commands, and slot paths must agree. It does not make every physical storage interface a supported boot target. Capacity and Growth ------------------- The misc reference configuration sets ``ROOTFS_PART_SIZE = "2048"``, ``APP_PART_SIZE = "1024"``, and ``BOOT_PART_SIZE = "1024"``, in MiB per slot. ``UNENCRYPTED_PART_SIZE`` defaults to 32 MiB. The initial LVM partition defaults to 4096 MiB; the QEMU fragment overrides it to 6144 MiB. The initial WIC LVM partition is a provisioning container, not a promise of usable space for all logical volumes at that size. Early boot grows the final partition to the target disk before creating the logical volumes. Two 2048 MiB rootfs slots and two 1024 MiB application slots alone require 6144 MiB inside LVM, before metadata and the persistent data filesystem. The disk must also hold both boot partitions and the unencrypted partition. Allow additional space for persistent data, filesystem overhead, and image growth. The QEMU installation example uses a 16 GiB disk. .. _os-etc-overlay: Persistent /etc Overlay ----------------------- The minimal and Weston image recipes enable ``read-only-rootfs`` and add ``overlayfs-etc`` when ``ORCOS_ROOTFS_ON_LVM`` is enabled, which is the default. This supplies a writable ``/etc`` while retaining the image's read-only rootfs policy. The physical-rootfs reference configuration does not enable this overlay. The common distro configuration selects an ext4 backing filesystem on ``/dev/mapper/${VG_LVM_LABEL}-${DATA_PART_LABEL}``, mounted at ``/data``. The OpenEmbedded ``overlayfs-etc`` class installs a pre-init wrapper at ``/sbin/init`` and preserves the original init as ``/sbin/init.orig``. The wrapper mounts the data filesystem and the merged ``/etc`` before starting systemd. .. list-table:: Configuration overlay layers :header-rows: 1 :widths: 20 40 40 * - Layer - Location - Purpose * - Lower - ``/etc`` from the selected rootfs image - Default configuration supplied by that image. * - Upper - ``/data/overlay-etc/upper`` - Persistent files added or changed through the merged ``/etc``, including overlay records of deleted files. * - Work - ``/data/overlay-etc/work`` - Working directory used by OverlayFS on the same data filesystem. Read and edit configuration through ``/etc``. Files without an upper-layer override come from the currently selected rootfs. Modified files override the image defaults, and deletion records continue to hide the corresponding lower files. The upper layer is shared by both slots and survives rootfs updates and rollback; it is not replaced by a RAUC bundle. The supplied overlay class does not migrate or reset configuration when the image changes. Review persistent configuration for compatibility in both update and rollback directions: an existing override can hide a new image default, and a service migration can affect configuration compatibility during rollback. To inspect the mounts on a running device: .. code-block:: sh awk '$2 == "/etc" || $2 == "/data" { print $2, $3, $4 }' /proc/mounts ``/etc`` should be an ``overlay`` mount using the upper and work directories above, and ``/data`` should be the persistent ext4 filesystem. The supplied pre-init template logs mount failures and continues to start init, so service startup alone does not confirm that writable configuration is persistent. .. _os-filesystem-contents: File System Contents ==================== .. list-table:: Runtime state and mount points :header-rows: 1 * - Path - Purpose and lifetime * - ``/data`` - Persistent LVM filesystem shared by both rootfs slots; holds writable configuration and service state across rootfs updates. * - ``/etc`` - Merged configuration view in rootfs-on-LVM images; see :ref:`os-etc-overlay`. * - ``/data/overlay-etc`` - Persistent upper layer and working directory for the ``/etc`` overlay. * - ``/data/docker`` and ``/data/.docker`` - Docker daemon data and the persistent target of ``/root/.docker``. * - ``/data/rauc`` - RAUC persistent update state. * - ``/data/userdata`` - Directory created for the configured OrchestraOS user. * - ``/data-unencrypted`` - Provisioning markers and, when encryption is selected, protected key material or derivation metadata needed before the encrypted LVM opens. * - ``/app`` - Application logical volume corresponding to the selected rootfs slot. * - ``/boot`` - Boot filesystem corresponding to the selected slot. * - ``/home/`` - User home installed by the image. Its presence does not give it the same persistence policy as the data logical volume. * - ``/run/fluent-bit`` - Volatile journal cursor database; recreated after reboot. Application layers define any additional platform integration state. .. _os-rauc-update-flow: RAUC Update Flow ================ .. figure:: images/orchestraos-updates.svg :alt: RAUC verifies a signed bundle and writes the inactive boot, rootfs, and application slot group. The device reboots into that group and applies its health policy. Shared data and the etc overlay are retained. :width: 100% :class: architecture-figure On-device update flow, illustrated with A running and B as the update target. Bootloader payload inclusion and fallback behaviour depend on the configured target and backend. Adding ``rauc`` to ``DISTRO_FEATURES`` selects the RAUC image integration. The reference RAUC bundle format is ``verity`` and its filename extension is ``.raucb``. .. list-table:: Backend and slot policy :header-rows: 1 * - Setting - U-Boot / EIG reference - QEMU UEFI reference * - ``RAUC_BOOTLOADER`` - ``uboot`` - ``efi`` * - ``RAUC_BOOTLOADER_ON_DISK`` - ``1`` on EIG; ``0`` on QEMU U-Boot. - ``0``; firmware is supplied by the virtual machine. * - ``ORCOS_BOOT_SLOT_FSTYPE`` - ``ext4`` - ``vfat`` * - Boot selection state - U-Boot environment, including slot order and retry counts. - EFI entries and firmware variables maintained with ``efibootmgr``. The bundle includes a bootloader payload only when ``RAUC_BOOTLOADER_ON_DISK`` is enabled, a boot-filesystem payload when ``ROOTFS_ON_LVM`` is true, and rootfs/application payloads. Boot payloads are named ``boot.ext4`` or ``boot.vfat``; rootfs and application payloads are ``rootfs.ext4`` and ``appfs.ext4``. For EIG platforms, bootloader selection accounts for the signing state and available U-Boot memory variants. ``ROOTFS_ON_LVM`` is true when either ``ORCOS_ROOTFS_ON_LVM`` or ``INITRAMFS_IMAGE_BUNDLE`` is true. This deliberately supports a separate initramfs, including EIGXS AHAB packaging. LVM rootfs slots use ``/dev/mapper/${VG_LVM_LABEL}-${ROOTFS_SLOT_*_LABEL}``; physical-rootfs slots use the configured disk partitions. Application slots use LVM in both cases. The rootfs and application slots are grouped under the corresponding boot slot in the rootfs-on-LVM configuration. Runtime services include RAUC, ``rauc-hawkbit-updater``, its OrchestraOS configuration, and a version reporter. RAUC stores persistent update state under ``/data/rauc``. Delivery endpoint and credentials are deployment configuration; the presence of an updater does not establish a connection to an update server. Slot Health and Persistent State ================================ Application health policy must decide when a newly booted slot is acceptable and arrange the appropriate RAUC good/bad decision. Installing a bundle does not demonstrate that the application is healthy. Persistent data and the ``/etc`` overlay also need compatibility review when planning rollback. The boot retry and slot-selection mechanisms are described in :ref:`os-architecture-boot`.