ref-manual: add overlayfs class

Submitted by Vyacheslav Yurkov on Aug. 14, 2021, 4:28 a.m. | Patch ID: 180072


Message ID
State Superseded
Headers show

Commit Message

Vyacheslav Yurkov Aug. 14, 2021, 4:28 a.m.
Signed-off-by: Vyacheslav Yurkov <>
 documentation/ref-manual/classes.rst | 46 ++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

Patch hide | download patch | download mbox

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index a98a64c43..5d33e81a1 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -1710,6 +1710,52 @@  one such example. However, being aware of this class can reduce the
 proliferation of different versions of similar classes across multiple
+.. _ref-classes-overlayfs:
+It's often desired in Embedded System design to have a read-only rootfs.
+But a lot of different applications might want to have a read-write access to
+some parts of a filesystem. It can be especially useful when your update mechanism
+overwrites the whole rootfs, but you want your application data to be preserved
+between updates. The ``overlayfs`` class provides a way to achieve that by means
+of overlayfs and at the same time keeping the base rootfs read-only.
+To use this class, set a mount point for a partition overlayfs is going to use as upper
+layer in your machine configuration. Underlying file system can be anything that
+is supported by overlayfs. This has to be done in your machine configuration::
+  OVERLAYFS_MOUNT_POINT[data] = "/data"
+.. note::
+  QA check fails to catch file existence if you redefine this variable in your recipe!
+The class assumes you have a data.mount systemd unit defined elsewhere in your BSP
+(e.g. in systemd-machine-units recipe) and it's installed to the image.
+Then you can specify writable directories on a recipe basis::
+  OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application"
+To support several mount points you can use a different variable flag. Assume we
+want to have a writable location on the file system, but not interested where the data
+survive a reboot. Then we could have a mnt-overlay.mount unit for a tmpfs file system.
+In your machine configuration::
+  OVERLAYFS_MOUNT_POINT[mnt-overlay] = "/mnt/overlay"
+and then in your recipe::
+  OVERLAYFS_WRITABLE_PATHS[mnt-overlay] = "/usr/share/another-application"
+.. note::
+   The class does not support /etc directory itself, because systemd depends on it
 .. _ref-classes-own-mirrors:


Vyacheslav Yurkov Aug. 23, 2021, 6:15 a.m.
This is a system generated Comment: Patch 180072 was automatically marked as superseded by patch 180148.