Yocto Overlayfs for etc: Mount Configuration Before the Real Init Starts
The device reaches a login prompt, yet changes to /etc do not survive reboot. With Yocto's overlayfs-etc feature, successful startup alone does not prove that the configuration overlay mounted. The generated preinit wrapper has its own entry-point selection and failure behavior, before ordinary system services run.
Inspect that wrapper and its backing storage rather than adding a late application mount service. The init manager already consumes /etc while it starts.
Select the early entry point deliberately
The Yocto overlayfs-etc reference enables the feature through IMAGE_FEATURES += "overlayfs-etc", rather than direct class inheritance. Machine configuration supplies OVERLAYFS_ETC_DEVICE, OVERLAYFS_ETC_MOUNT_POINT and OVERLAYFS_ETC_FSTYPE for the backing filesystem.
The default mode replaces the normal /sbin/init entry point with the generated wrapper and moves the original to /sbin/init.orig. The documentation warns that package-management conflicts with this mode because updating the init manager can overwrite the wrapper.
With OVERLAYFS_ETC_USE_ORIG_INIT_NAME = "0", the wrapper becomes /sbin/preinit and the original init remains in place. Boot configuration must then select the wrapper. The Linux kernel parameter reference defines init= as selecting an executable instead of the normal init path; with the documented directory layout, the intended parameter is init=/sbin/preinit.
Check the actual boot path, especially when an initramfs participates. Merely installing /sbin/preinit cannot make a boot sequence that still executes /sbin/init pass through it.
Inspect the generated image before diagnosing the board
The examined class implementation generates the wrapper during rootfs postprocessing. It rejects empty device, mount-point and filesystem-type settings, substitutes the selected template and marks the result executable.
Inspect the assembled image's entry point and generated script. Confirm its device and real-init path rather than assuming the configuration fragment won precedence. In replacement mode, verify both the wrapper and renamed original exist. In preinit mode, verify the boot configuration actually selects the generated file.
These checks separate a construction error from a runtime mount failure. A missing wrapper, a wrapper containing an obsolete device path and a correct wrapper unable to mount that device are three different faults.
Account for what the early script can actually prepare
In the examined preinit template, the default directory-creation branch attempts to remount the root writable and creates several mount-point directories. OVERLAYFS_ETC_CREATE_MOUNT_DIRS controls that branch. For an immutable root that cannot support this preparation, pre-create the required directories in the image and evaluate disabling the branch rather than assuming the remount can succeed.
The script mounts proc and sysfs, then attempts the configured backing filesystem. Beneath that mount it uses overlay-etc/upper and overlay-etc/work, mounting the merged view at /etc with the original /etc as its lower directory.
Inspect whether the backing device and required filesystem support are available at this early stage. The examined template does not wait in a retry loop for a late-arriving device. A mount that works after normal userspace initialization may therefore fail in preinit.
Treat mount failure as a separate boot result
The template reports a backing-mount failure or an overlay-mount failure, then continues to execute the selected real init. It does not implement a fail-closed boot policy. Consequently, a login prompt and the final preinit progress message are insufficient acceptance checks.
Read the early console output and /proc/mounts. Verify both the intended backing filesystem and an overlay mounted at /etc. On a controlled test image, create a disposable configuration file through /etc and verify the corresponding upper file before checking persistence after reboot.
The Linux OverlayFS documentation also explains why an existing upper file can hide the same path in a newer lower image. Therefore, mounting successfully is not a configuration migration strategy. The Yocto class explicitly leaves update and migration policy outside its scope; test that policy separately from this early-mount diagnosis.
