summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
authorVyacheslav Yurkov <uvv.mail@gmail.com>2021-08-22 22:14:54 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2021-09-18 13:03:45 +0100
commit62b13474bfe8a053d34523785c446c5592834adf (patch)
treea96ceec83f4d04ea5c298ba71a9352eda5849f54 /documentation/ref-manual
parent70059b37c748d49e9fe83b26d4dc95308df18309 (diff)
downloadpoky-62b13474bfe8a053d34523785c446c5592834adf.tar.gz
ref-manual: add overlayfs class
(From yocto-docs rev: 5bd2f3c0bbf4178e381aec2b7de57ef8289c2271) Signed-off-by: Vyacheslav Yurkov <uvv.mail@gmail.com> Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/classes.rst49
1 files changed, 49 insertions, 0 deletions
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 1b685370c4..5c60fd8c82 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -1710,6 +1710,55 @@ one such example. However, being aware of this class can reduce the
1710proliferation of different versions of similar classes across multiple 1710proliferation of different versions of similar classes across multiple
1711layers. 1711layers.
1712 1712
1713.. _ref-classes-overlayfs:
1714
1715``overlayfs.bbclass``
1716=======================
1717
1718It's often desired in Embedded System design to have a read-only rootfs.
1719But a lot of different applications might want to have read-write access to
1720some parts of a filesystem. It can be especially useful when your update mechanism
1721overwrites the whole rootfs, but you may want your application data to be preserved
1722between updates. The :ref:`overlayfs <ref-classes-overlayfs>` class provides a way
1723to achieve that by means of ``overlayfs`` and at the same time keeping the base
1724rootfs read-only.
1725
1726To use this class, set a mount point for a partition ``overlayfs`` is going to use as upper
1727layer in your machine configuration. The underlying file system can be anything that
1728is supported by ``overlayfs``. This has to be done in your machine configuration::
1729
1730 OVERLAYFS_MOUNT_POINT[data] = "/data"
1731
1732.. note::
1733
1734 * QA checks fail to catch file existence if you redefine this variable in your recipe!
1735 * Only the existence of the systemd mount unit file is checked, not its contents.
1736 * To get more details on ``overlayfs``, its internals and supported operations, please refer
1737 to the official documentation of the `Linux kernel <https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html>`_.
1738
1739The class assumes you have a ``data.mount`` systemd unit defined elsewhere in your BSP
1740(e.g. in ``systemd-machine-units`` recipe) and it's installed into the image.
1741
1742Then you can specify writable directories on a recipe basis (e.g. in my-application.bb)::
1743
1744 OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application"
1745
1746To support several mount points you can use a different variable flag. Assuming we
1747want to have a writable location on the file system, but do not need that the data
1748survives a reboot, then we could have a ``mnt-overlay.mount`` unit for a ``tmpfs`` file system.
1749
1750In your machine configuration::
1751
1752 OVERLAYFS_MOUNT_POINT[mnt-overlay] = "/mnt/overlay"
1753
1754and then in your recipe::
1755
1756 OVERLAYFS_WRITABLE_PATHS[mnt-overlay] = "/usr/share/another-application"
1757
1758.. note::
1759
1760 The class does not support the ``/etc`` directory itself, because ``systemd`` depends on it.
1761
1713.. _ref-classes-own-mirrors: 1762.. _ref-classes-own-mirrors:
1714 1763
1715``own-mirrors.bbclass`` 1764``own-mirrors.bbclass``