[PATCH v3 0/3] Overlayfs improvements

[PATCH v3 0/3] Overlayfs improvements

[uvv.mail]

From: Vyacheslav Yurkov <uvv.mail@gmail.com>

Changes to v2:
- Improved commit messages

Vyacheslav Yurkov (3):
  overlayfs: Fix the QA skip for ignored mounts
  oe-selftest: overlayfs: Make the test more deterministic
  oe-selftest: overlayfs: Add a demo case for /etc

 meta/lib/oe/overlayfs.py                  |   3 +-
 meta/lib/oeqa/selftest/cases/overlayfs.py | 103 +++++++++++++++++++++-
 2 files changed, 103 insertions(+), 3 deletions(-)

[PATCH v3 1/3] overlayfs: Fix the QA skip for ignored mounts

[uvv.mail]

From: Vyacheslav Yurkov <uvv.mail@gmail.com>

The supressing of QA check for mounts should happens twice, at parsing stage
and at rootfs postprocessing. If the mount point is configured to be skipped,
but it is still present in the configuration (machine or distro), then the
parsing would complain.

Signed-off-by: Vyacheslav Yurkov <uvv.mail@gmail.com>
---
 meta/lib/oe/overlayfs.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/meta/lib/oe/overlayfs.py b/meta/lib/oe/overlayfs.py
index 5a5ea03d45..3805746d90 100644
--- a/meta/lib/oe/overlayfs.py
+++ b/meta/lib/oe/overlayfs.py
@@ -33,7 +33,8 @@ def unitFileList(d):
     # check that we have required mount points set first
     requiredMountPoints = d.getVarFlags('OVERLAYFS_WRITABLE_PATHS')
     for mountPoint in requiredMountPoints:
-        if mountPoint not in overlayMountPoints:
+        qaSkip = (d.getVarFlag("OVERLAYFS_QA_SKIP", mountPoint) or "").split()
+        if mountPoint not in overlayMountPoints and not "mount-configured" in qaSkip:
             bb.fatal("Missing required mount point for OVERLAYFS_MOUNT_POINT[%s] in your MACHINE configuration" % mountPoint)
 
     for mountPoint in overlayMountPoints:

Re: [OE-core] [PATCH v3 1/3] overlayfs: Fix the QA skip for ignored mounts

[Paul Barker]

[-- Attachment #1: Type: text/plain, Size: 2145 bytes --]

On Wed, 2026-01-14 at 18:54 +0000, Vyacheslav Yurkov via
lists.openembedded.org wrote:
> From: Vyacheslav Yurkov <uvv.mail@gmail.com>
> 
> The supressing of QA check for mounts should happens twice, at parsing stage
> and at rootfs postprocessing. If the mount point is configured to be skipped,
> but it is still present in the configuration (machine or distro), then the
> parsing would complain.

Thanks for respinning these patches.

I'm still unsure why the check is being performed twice. Are we checking
for different errors at parse time and rootfs time?

Also, can we convert this to fit in our existing QA framework so that it
is controlled by the WARN_QA/ERROR_QA variables?

> 
> Signed-off-by: Vyacheslav Yurkov <uvv.mail@gmail.com>
> ---
>  meta/lib/oe/overlayfs.py | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/meta/lib/oe/overlayfs.py b/meta/lib/oe/overlayfs.py
> index 5a5ea03d45..3805746d90 100644
> --- a/meta/lib/oe/overlayfs.py
> +++ b/meta/lib/oe/overlayfs.py
> @@ -33,7 +33,8 @@ def unitFileList(d):
>      # check that we have required mount points set first
>      requiredMountPoints = d.getVarFlags('OVERLAYFS_WRITABLE_PATHS')
>      for mountPoint in requiredMountPoints:
> -        if mountPoint not in overlayMountPoints:
> +        qaSkip = (d.getVarFlag("OVERLAYFS_QA_SKIP", mountPoint) or "").split()
> +        if mountPoint not in overlayMountPoints and not "mount-configured" in qaSkip:
>              bb.fatal("Missing required mount point for OVERLAYFS_MOUNT_POINT[%s] in your MACHINE configuration" % mountPoint)
>  
>      for mountPoint in overlayMountPoints:
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#229369): https://lists.openembedded.org/g/openembedded-core/message/229369
> Mute This Topic: https://lists.openembedded.org/mt/117266570/1826184
> Group Owner: openembedded-core+owner@lists.openembedded.org
> Unsubscribe: https://lists.openembedded.org/g/openembedded-core/unsub [paul@pbarker.dev]
> -=-=-=-=-=-=-=-=-=-=-=-
> 

Best regards,

-- 
Paul Barker


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 252 bytes --]

Re: [OE-core] [PATCH v3 1/3] overlayfs: Fix the QA skip for ignored mounts

[Vyacheslav Yurkov]

This is actually a good point, but I'm not sure how WARN_QA/ERROR_QA can 
be utilized here. WARN_QA/ERROR_QA expects one keyword, but 
OVERLAYFS_QA_SKIP expects a flag per mount unit. If we simplify it to 
WARN_QA/ERROR_QA, then we enable/disable the QA for all mount units. 
This will be a breaking change though, but it sounds like it might 
simplify things a bit. Do you think that would be better to use 
WARN_QA/ERROR_QA instead of current mechanism?

As for the check performed twice question. The file list is populated / 
expanded at the parsing stage, but the actual QA is performed at the 
rootfs postprocessing, because the overlayfs class works on a recipe 
basis, so to check if everything is provided the whole file system is 
needed.

Slava

On 15.01.2026 14:41, Paul Barker wrote:
> On Wed, 2026-01-14 at 18:54 +0000, Vyacheslav Yurkov via
> lists.openembedded.org wrote:
>> From: Vyacheslav Yurkov <uvv.mail@gmail.com>
>>
>> The supressing of QA check for mounts should happens twice, at parsing stage
>> and at rootfs postprocessing. If the mount point is configured to be skipped,
>> but it is still present in the configuration (machine or distro), then the
>> parsing would complain.
> Thanks for respinning these patches.
>
> I'm still unsure why the check is being performed twice. Are we checking
> for different errors at parse time and rootfs time?
>
> Also, can we convert this to fit in our existing QA framework so that it
> is controlled by the WARN_QA/ERROR_QA variables?
>
>> Signed-off-by: Vyacheslav Yurkov <uvv.mail@gmail.com>
>> ---
>>   meta/lib/oe/overlayfs.py | 3 ++-
>>   1 file changed, 2 insertions(+), 1 deletion(-)
>>
>> diff --git a/meta/lib/oe/overlayfs.py b/meta/lib/oe/overlayfs.py
>> index 5a5ea03d45..3805746d90 100644
>> --- a/meta/lib/oe/overlayfs.py
>> +++ b/meta/lib/oe/overlayfs.py
>> @@ -33,7 +33,8 @@ def unitFileList(d):
>>       # check that we have required mount points set first
>>       requiredMountPoints = d.getVarFlags('OVERLAYFS_WRITABLE_PATHS')
>>       for mountPoint in requiredMountPoints:
>> -        if mountPoint not in overlayMountPoints:
>> +        qaSkip = (d.getVarFlag("OVERLAYFS_QA_SKIP", mountPoint) or "").split()
>> +        if mountPoint not in overlayMountPoints and not "mount-configured" in qaSkip:
>>               bb.fatal("Missing required mount point for OVERLAYFS_MOUNT_POINT[%s] in your MACHINE configuration" % mountPoint)
>>   
>>       for mountPoint in overlayMountPoints:
>> -=-=-=-=-=-=-=-=-=-=-=-
>> Links: You receive all messages sent to this group.
>> View/Reply Online (#229369): https://lists.openembedded.org/g/openembedded-core/message/229369
>> Mute This Topic: https://lists.openembedded.org/mt/117266570/1826184
>> Group Owner: openembedded-core+owner@lists.openembedded.org
>> Unsubscribe: https://lists.openembedded.org/g/openembedded-core/unsub [paul@pbarker.dev]
>> -=-=-=-=-=-=-=-=-=-=-=-
>>

[PATCH v3 2/3] oe-selftest: overlayfs: Make the test more deterministic

[uvv.mail]

From: Vyacheslav Yurkov <uvv.mail@gmail.com>

The test orignally was written under assumption that poky distro is
used. When poky-altcft is used for example, then systemd is already set
in DISTRO_FETURES, which the test did not expect.

Signed-off-by: Vyacheslav Yurkov <uvv.mail@gmail.com>
---
 meta/lib/oeqa/selftest/cases/overlayfs.py | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/meta/lib/oeqa/selftest/cases/overlayfs.py b/meta/lib/oeqa/selftest/cases/overlayfs.py
index 580fbdcb9c..3e55e97927 100644
--- a/meta/lib/oeqa/selftest/cases/overlayfs.py
+++ b/meta/lib/oeqa/selftest/cases/overlayfs.py
@@ -5,7 +5,7 @@
 #
 
 from oeqa.selftest.case import OESelftestTestCase
-from oeqa.utils.commands import bitbake, runqemu, get_bb_vars
+from oeqa.utils.commands import bitbake, runqemu, get_bb_vars, get_bb_var
 from oeqa.core.decorator import OETestTag
 from oeqa.core.decorator.data import skipIfNotMachine
 
@@ -46,7 +46,8 @@ inherit overlayfs
         res = bitbake('core-image-minimal', ignore_status=True)
         line = getline(res, "overlayfs-user was skipped: missing required distro features")
         self.assertTrue("overlayfs" in res.output, msg=res.output)
-        self.assertTrue("systemd" in res.output, msg=res.output)
+        if not "systemd" in get_bb_var('DISTRO_FEATURES'):
+            self.assertTrue("systemd" in res.output, msg=res.output)
         self.assertTrue("ERROR: Required build target 'core-image-minimal' has no buildable providers." in res.output, msg=res.output)
 
     def test_not_all_units_installed(self):

Re: [OE-core] [PATCH v3 2/3] oe-selftest: overlayfs: Make the test more deterministic

[Paul Barker]

[-- Attachment #1: Type: text/plain, Size: 2316 bytes --]

On Wed, 2026-01-14 at 18:54 +0000, Vyacheslav Yurkov via
lists.openembedded.org wrote:
> From: Vyacheslav Yurkov <uvv.mail@gmail.com>
> 
> The test orignally was written under assumption that poky distro is
> used. When poky-altcft is used for example, then systemd is already set
> in DISTRO_FETURES, which the test did not expect.

Hi,

The commit title here still talks about determinism. The test case was
deterministic though - previously it would always fail if systemd was
already in DISTRO_FEATURES. I think I misunderstood a little last time,
but this still needs renaming.

I also wonder why we're testing this here. Perhaps this can be turned
into a more generic test that REQUIRED_DISTRO_FEATURES behaves as
expected - we can use the overlayfs bbclass as part of that as we know
it sets REQUIRED_DISTRO_FEATURES.

> 
> Signed-off-by: Vyacheslav Yurkov <uvv.mail@gmail.com>
> ---
>  meta/lib/oeqa/selftest/cases/overlayfs.py | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
> 
> diff --git a/meta/lib/oeqa/selftest/cases/overlayfs.py b/meta/lib/oeqa/selftest/cases/overlayfs.py
> index 580fbdcb9c..3e55e97927 100644
> --- a/meta/lib/oeqa/selftest/cases/overlayfs.py
> +++ b/meta/lib/oeqa/selftest/cases/overlayfs.py
> @@ -5,7 +5,7 @@
>  #
>  
>  from oeqa.selftest.case import OESelftestTestCase
> -from oeqa.utils.commands import bitbake, runqemu, get_bb_vars
> +from oeqa.utils.commands import bitbake, runqemu, get_bb_vars, get_bb_var
>  from oeqa.core.decorator import OETestTag
>  from oeqa.core.decorator.data import skipIfNotMachine
>  
> @@ -46,7 +46,8 @@ inherit overlayfs
>          res = bitbake('core-image-minimal', ignore_status=True)
>          line = getline(res, "overlayfs-user was skipped: missing required distro features")
>          self.assertTrue("overlayfs" in res.output, msg=res.output)
> -        self.assertTrue("systemd" in res.output, msg=res.output)
> +        if not "systemd" in get_bb_var('DISTRO_FEATURES'):
> +            self.assertTrue("systemd" in res.output, msg=res.output)
>          self.assertTrue("ERROR: Required build target 'core-image-minimal' has no buildable providers." in res.output, msg=res.output)
>  
>      def test_not_all_units_installed(self):

Best regards,

-- 
Paul Barker


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 252 bytes --]

[PATCH v3 3/3] oe-selftest: overlayfs: Add a demo case for /etc

[uvv.mail]

From: Vyacheslav Yurkov <uvv.mail@gmail.com>

/etc is a special directory. It's possible to create a mount unit for
it, but many system services that start early at boot time will not
rescan its content when you mount overlay on top. The added test case
demonstrates this by adding a sample systemd service and enabling it in
overlay.

Signed-off-by: Vyacheslav Yurkov <uvv.mail@gmail.com>
---
 meta/lib/oeqa/selftest/cases/overlayfs.py | 98 +++++++++++++++++++++++
 1 file changed, 98 insertions(+)

diff --git a/meta/lib/oeqa/selftest/cases/overlayfs.py b/meta/lib/oeqa/selftest/cases/overlayfs.py
index 3e55e97927..426b4ccee3 100644
--- a/meta/lib/oeqa/selftest/cases/overlayfs.py
+++ b/meta/lib/oeqa/selftest/cases/overlayfs.py
@@ -263,6 +263,104 @@ EOT
 
         self._test_correct_image('systemd-machine-units', systemd_machine_unit_append)
 
+    @skipIfNotMachine("qemux86-64", "tests are qemux86-64 specific currently")
+    def test_etc_mount(self):
+        """
+        Summary:   /etc is not supposed to be used with overlayfs.bbclass
+        Expected:  Observe inconsistencies after using etc overlay with a mount unit
+        Author:    Vyacheslav Yurkov <uvv.mail@gmail.com>
+        """
+        systemd_machine_unit_append = """
+SYSTEMD_SERVICE:${PN} += " \
+    data.mount \
+    etc.mount \
+"
+
+do_install:append() {
+    install -d ${D}${systemd_system_unitdir}
+    install -d ${D}${ROOT_HOME}
+    cat <<EOT > ${D}${systemd_system_unitdir}/etc.mount
+[Unit]
+Description=OverlayFS mount for /etc directory
+DefaultDependencies=no
+RequiresMountsFor=/data
+
+[Mount]
+What=overlay
+Where=/etc
+Type=overlay
+Options=lowerdir=/etc,upperdir=/data/overlay/etc,workdir=/data/overlay-workdir/etc
+[Install]
+WantedBy=local-fs.target
+EOT
+
+    cat <<EOT >${D}${systemd_system_unitdir}/data.mount
+[Unit]
+Description=Persistent storage partition
+
+[Mount]
+What=/dev/sda3
+Where=/data
+Type=ext4
+Options=defaults
+
+[Install]
+WantedBy=local-fs.target
+EOT
+    cat <<EOT > ${D}${ROOT_HOME}/test-daemon.service
+[Unit]
+Description=My one-shot task
+After=local-fs.target
+
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/echo test
+RemainAfterExit=yes
+
+[Install]
+WantedBy=multi-user.target
+EOT
+}
+
+FILES:${PN} += "${ROOT_HOME}"
+"""
+
+        config = """
+IMAGE_INSTALL:append = " systemd-machine-units"
+DISTRO_FEATURES:append = " overlayfs"
+
+# Use systemd as init manager
+INIT_MANAGER = "systemd"
+
+# enable overlayfs in the kernel
+KERNEL_EXTRA_FEATURES:append = " features/overlayfs/overlayfs.scc"
+
+IMAGE_FSTYPES += "wic"
+WKS_FILE = "overlayfs_etc.wks.in"
+OVERLAYFS_ROOTFS_TYPE = "ext4"
+"""
+
+        self.write_config(config)
+
+        machine_inc = """
+OVERLAYFS_MOUNT_POINT[etc] = "/etc"
+OVERLAYFS_QA_SKIP[mnt-overlay] = "mount-configured"
+"""
+        self.set_machine_config(machine_inc)
+        self.write_recipeinc('systemd-machine-units', systemd_machine_unit_append)
+        bitbake('core-image-minimal')
+        with runqemu('core-image-minimal', image_fstype='wic', discard_writes=False) as qemu:
+            test_daemon_path = get_bb_var('ROOT_HOME') + '/test-daemon.service'
+            status, output = qemu.run_serial('cp -f ' + test_daemon_path + ' /etc/systemd/system/')
+            status, output = qemu.run_serial("systemctl enable test-daemon")
+            status, output = qemu.run_serial("sync")
+        with runqemu('core-image-minimal', image_fstype='wic') as qemu:
+            # Check the test service status. It's enabled and supposed to start, but it didn't
+            status, output = qemu.run_serial("systemctl is-enabled test-daemon")
+            self.assertTrue("enabled" in output, msg=output)
+            status, output = qemu.run_serial("systemctl is-active test-daemon")
+            self.assertTrue("inactive" in output, msg=output)
+
 @OETestTag("runqemu")
 class OverlayFSEtcRunTimeTests(OESelftestTestCase):
     """overlayfs-etc class tests"""

Re: [OE-core] [PATCH v3 3/3] oe-selftest: overlayfs: Add a demo case for /etc

[Paul Barker]

[-- Attachment #1: Type: text/plain, Size: 4994 bytes --]

On Wed, 2026-01-14 at 18:54 +0000, Vyacheslav Yurkov via
lists.openembedded.org wrote:
> From: Vyacheslav Yurkov <uvv.mail@gmail.com>
> 
> /etc is a special directory. It's possible to create a mount unit for
> it, but many system services that start early at boot time will not
> rescan its content when you mount overlay on top. The added test case
> demonstrates this by adding a sample systemd service and enabling it in
> overlay.

Hi,

I still don't understand what we're actually trying to test here. We
know that overlayfs.bbclass can't be used this way. The documentation
already says "The class does not support the /etc directory itself" and
points users at the overlayfs-etc class. What do we gain by having a
test case for this?

Perhaps what we should have is a check at build time to catch '/etc/' in
an OVERLAYFS_MOUNT_POINT entry, which prints an error telling the user
to use overlayfs-etc instead. That way the runtime misbehaviour is
actually prevented.

> 
> Signed-off-by: Vyacheslav Yurkov <uvv.mail@gmail.com>
> ---
>  meta/lib/oeqa/selftest/cases/overlayfs.py | 98 +++++++++++++++++++++++
>  1 file changed, 98 insertions(+)
> 
> diff --git a/meta/lib/oeqa/selftest/cases/overlayfs.py b/meta/lib/oeqa/selftest/cases/overlayfs.py
> index 3e55e97927..426b4ccee3 100644
> --- a/meta/lib/oeqa/selftest/cases/overlayfs.py
> +++ b/meta/lib/oeqa/selftest/cases/overlayfs.py
> @@ -263,6 +263,104 @@ EOT
>  
>          self._test_correct_image('systemd-machine-units', systemd_machine_unit_append)
>  
> +    @skipIfNotMachine("qemux86-64", "tests are qemux86-64 specific currently")
> +    def test_etc_mount(self):
> +        """
> +        Summary:   /etc is not supposed to be used with overlayfs.bbclass
> +        Expected:  Observe inconsistencies after using etc overlay with a mount unit
> +        Author:    Vyacheslav Yurkov <uvv.mail@gmail.com>
> +        """
> +        systemd_machine_unit_append = """
> +SYSTEMD_SERVICE:${PN} += " \
> +    data.mount \
> +    etc.mount \
> +"
> +
> +do_install:append() {
> +    install -d ${D}${systemd_system_unitdir}
> +    install -d ${D}${ROOT_HOME}
> +    cat <<EOT > ${D}${systemd_system_unitdir}/etc.mount
> +[Unit]
> +Description=OverlayFS mount for /etc directory
> +DefaultDependencies=no
> +RequiresMountsFor=/data
> +
> +[Mount]
> +What=overlay
> +Where=/etc
> +Type=overlay
> +Options=lowerdir=/etc,upperdir=/data/overlay/etc,workdir=/data/overlay-workdir/etc
> +[Install]
> +WantedBy=local-fs.target
> +EOT
> +
> +    cat <<EOT >${D}${systemd_system_unitdir}/data.mount
> +[Unit]
> +Description=Persistent storage partition
> +
> +[Mount]
> +What=/dev/sda3
> +Where=/data
> +Type=ext4
> +Options=defaults
> +
> +[Install]
> +WantedBy=local-fs.target
> +EOT
> +    cat <<EOT > ${D}${ROOT_HOME}/test-daemon.service
> +[Unit]
> +Description=My one-shot task
> +After=local-fs.target
> +
> +[Service]
> +Type=oneshot
> +ExecStart=/usr/bin/echo test
> +RemainAfterExit=yes
> +
> +[Install]
> +WantedBy=multi-user.target
> +EOT
> +}
> +
> +FILES:${PN} += "${ROOT_HOME}"
> +"""
> +
> +        config = """
> +IMAGE_INSTALL:append = " systemd-machine-units"
> +DISTRO_FEATURES:append = " overlayfs"
> +
> +# Use systemd as init manager
> +INIT_MANAGER = "systemd"
> +
> +# enable overlayfs in the kernel
> +KERNEL_EXTRA_FEATURES:append = " features/overlayfs/overlayfs.scc"
> +
> +IMAGE_FSTYPES += "wic"
> +WKS_FILE = "overlayfs_etc.wks.in"
> +OVERLAYFS_ROOTFS_TYPE = "ext4"
> +"""
> +
> +        self.write_config(config)
> +
> +        machine_inc = """
> +OVERLAYFS_MOUNT_POINT[etc] = "/etc"
> +OVERLAYFS_QA_SKIP[mnt-overlay] = "mount-configured"
> +"""
> +        self.set_machine_config(machine_inc)
> +        self.write_recipeinc('systemd-machine-units', systemd_machine_unit_append)
> +        bitbake('core-image-minimal')
> +        with runqemu('core-image-minimal', image_fstype='wic', discard_writes=False) as qemu:
> +            test_daemon_path = get_bb_var('ROOT_HOME') + '/test-daemon.service'
> +            status, output = qemu.run_serial('cp -f ' + test_daemon_path + ' /etc/systemd/system/')
> +            status, output = qemu.run_serial("systemctl enable test-daemon")
> +            status, output = qemu.run_serial("sync")
> +        with runqemu('core-image-minimal', image_fstype='wic') as qemu:
> +            # Check the test service status. It's enabled and supposed to start, but it didn't
> +            status, output = qemu.run_serial("systemctl is-enabled test-daemon")
> +            self.assertTrue("enabled" in output, msg=output)
> +            status, output = qemu.run_serial("systemctl is-active test-daemon")
> +            self.assertTrue("inactive" in output, msg=output)
> +
>  @OETestTag("runqemu")
>  class OverlayFSEtcRunTimeTests(OESelftestTestCase):
>      """overlayfs-etc class tests"""

Best regards,

-- 
Paul Barker


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 252 bytes --]