ref-manual: add overlayfs class
PATCH v2 1/1 ref-manual: add overlayfs class
Signed-off-by Vyacheslav Yurkov <[email protected]>
--- documentation/ref-manual/classes.rst | 49 ++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+)
documentation/ref-manual/classes.rst +49 -0
@@ -1710,6 +1710,55 @@ one such example. However, being aware of this class can reduce the proliferation of different versions of similar classes across multiple layers. +.. _ref-classes-overlayfs: + +``overlayfs.bbclass`` +======================= + +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 :ref:`overlayfs <ref-classes-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! + * Only existence of the systemd mount unit file is checked, not its content. + * To get more details on overlayfs, its internals and supported operations, please refer + to the official documentation of the `Linux kernel <https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html>`_ + +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 (e.g. in my-application.bb):: + + OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application" + +To support several mount points you can use a different variable flag. Assuming we +want to have a writable location on the file system, but not interested where the data +survives 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: ``own-mirrors.bbclass``
Signature · 1 line
2.28.0
Hi Slava,
Quoted 55 lines · Vyacheslav Yurkov
Signed-off-by Vyacheslav Yurkov <[email protected]>--- documentation/ref-manual/classes.rst | 49 ++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+)documentation/ref-manual/classes.rst +42
-0@@ -1710,6 +1710,55 @@ one such example. However, being aware of this class can reduce the proliferation of different versions of similar classes across multiple layers. +.. _ref-classes-overlayfs: + +``overlayfs.bbclass`` +======================= + +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 :ref:`overlayfs <ref-classes-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! + * Only existence of the systemd mount unit file is checked, not its content. + * To get more details on overlayfs, its internals and supported operations, please refer + to the official documentation of the `Linux kernel <https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html>`_ + +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 (e.g. in my-application.bb):: + + OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application" + +To support several mount points you can use a different variable flag. Assuming we +want to have a writable location on the file system, but not interested where the data +survives 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::
documentation/ref-manual/classes.rst one such example. However, being aware of this class can reduce the · line 1764
Quoted 10 lines
documentation/ref-manual/classes.rst +7
-0+ + 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: ``own-mirrors.bbclass``
Thanks for the code, for the documentation patch and its update.
I just added minor (mostly grammar) tweaks, but after those:
Reviewed-by Michael Opdenacker <[email protected]>
Now merged into "master-next".
Cheers,
Michael.
Signature · 3 lines
Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com