[PATCH] ref-manual: update overlayfs class

[PATCH] ref-manual: update overlayfs class

[Vyacheslav Yurkov]

Describe how to use a generated helper service to set up a proper
systemd dependency chain.

Signed-off-by: Vyacheslav Yurkov <uvv.mail@gmail.com>
---
 documentation/ref-manual/classes.rst | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 9b1ead66b..1638f6ea0 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -1742,7 +1742,8 @@ Then you can specify writable directories on a recipe basis (e.g. in my-applicat
 
 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 do not need that the data
-survives a reboot, then we could have a ``mnt-overlay.mount`` unit for a ``tmpfs`` file system.
+survives a reboot, then we could have a ``mnt-overlay.mount`` unit for a ``tmpfs`` 
+file system.
 
 In your machine configuration::
 
@@ -1752,6 +1753,22 @@ and then in your recipe::
 
   OVERLAYFS_WRITABLE_PATHS[mnt-overlay] = "/usr/share/another-application"
 
+On a practical note, your application recipe might use several mount points,
+therefore you'd like your application to start only when all overlays are mounted
+otherwise you might end up in a situation when application would write to an actual
+underlying file system (if it allows it) or could't write at all (for RO file systems).
+To achieve that :ref:`overlayfs <ref-classes-overlayfs>` provides another helper 
+service, which you can use to set dependencies on. The systemd dependency chain makes
+sure the service start only when all ``overlayfs`` mount points used in the recipe 
+are mounted. File name is fixed to ``${PN}-overlays.service``, so you can depend only 
+on this service in your application service file. E.g. if you have a recipe 
+``application.bb`` and a corresponding start-up service ``application.service``, you 
+can add dependencies as follows::
+
+  [Unit]
+  After=application-overlays.service
+  Requires=application-overlays.service
+
 .. note::
 
    The class does not support the ``/etc`` directory itself, because ``systemd`` depends on it.
-- 
2.28.0

Re: [docs] [PATCH] ref-manual: update overlayfs class

[Quentin Schulz]

Hi Vyacheslav,

On Mon, Nov 01, 2021 at 12:58:42PM +0100, Vyacheslav Yurkov wrote:
> Describe how to use a generated helper service to set up a proper
> systemd dependency chain.
> 
> Signed-off-by: Vyacheslav Yurkov <uvv.mail@gmail.com>
> ---
>  documentation/ref-manual/classes.rst | 19 ++++++++++++++++++-
>  1 file changed, 18 insertions(+), 1 deletion(-)
> 
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index 9b1ead66b..1638f6ea0 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -1742,7 +1742,8 @@ Then you can specify writable directories on a recipe basis (e.g. in my-applicat
>  
>  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 do not need that the data
> -survives a reboot, then we could have a ``mnt-overlay.mount`` unit for a ``tmpfs`` file system.
> +survives a reboot, then we could have a ``mnt-overlay.mount`` unit for a ``tmpfs`` 
> +file system.
>  
>  In your machine configuration::
>  
> @@ -1752,6 +1753,22 @@ and then in your recipe::
>  
>    OVERLAYFS_WRITABLE_PATHS[mnt-overlay] = "/usr/share/another-application"
>  
> +On a practical note, your application recipe might use several mount points,
> +therefore you'd like your application to start only when all overlays are mounted
> +otherwise you might end up in a situation when application would write to an actual
> +underlying file system (if it allows it) or could't write at all (for RO file systems).

If I may suggest:

"""
On a practical note, your application recipe might require multiple
overlays to be mounted before running to avoid writing to the underlying
file system (which can be forbidden in case of read-only file system).
"""

> +To achieve that :ref:`overlayfs <ref-classes-overlayfs>` provides another helper 
> +service, which you can use to set dependencies on. The systemd dependency chain makes
> +sure the service start only when all ``overlayfs`` mount points used in the recipe 
> +are mounted. File name is fixed to ``${PN}-overlays.service``, so you can depend only 
> +on this service in your application service file. E.g. if you have a recipe 
> +``application.bb`` and a corresponding start-up service ``application.service``, you 
> +can add dependencies as follows::
> +

If I may suggest:

"""
[...] provides a ``systemd`` helper service for mounting overlays. This helper
service is named ``${PN}-overlays.service`` and can be depended on in your
application recipe (named ``application`` in the following example) ``systemd``
unit by adding to the unit the following::
"""

> +  [Unit]
> +  After=application-overlays.service
> +  Requires=application-overlays.service
> +

I'm suggesting those to make the paragraph a bit easier to read and
strip it from explanations I'm not sure we care to have in classes.rst
since they are implementation details?

Thanks for the patch!
Quentin