[PATCH 1/2] ref-manual: add overlayfs-etc class

[PATCH 1/2] ref-manual: add overlayfs-etc class

[Vyacheslav Yurkov]

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

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 2c191f407..a5b01c2cf 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -1769,6 +1769,47 @@ to the unit the following::
 .. note::
 
    The class does not support the ``/etc`` directory itself, because ``systemd`` depends on it.
+   In order to get ``/etc`` in overlayfs see :ref:`overlayfs-etc <ref-classes-overlayfs-etc>` 
+
+.. _ref-classes-overlayfs-etc:
+
+``overlayfs-etc.bbclass``
+=========================
+
+In order to have ``/etc`` directory in overlayfs a special handling at early 
+boot stage is required.  The idea is to supply a custom init script that mounts
+``/etc`` before launching actual init program, because the latter already
+requires ``/etc`` to be mounted
+
+.. note::
+
+   This class must not be inherited directly. Use corresponding IMAGE_FEATURE
+
+Your machine configuration should define at least device, mount point, and file system type
+you are going to use for ``overlayfs``::
+
+  OVERLAYFS_ETC_MOUNT_POINT = "/data"
+  OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2"
+  OVERLAYFS_ETC_FSTYPE ?= "ext4"
+
+To control more mount options you should consider setting mount options
+(``defaults`` is used by default)::
+
+  OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync"
+
+The class provides two options for ``/sbin/init`` generation:
+
+* Default option is to rename original ``/sbin/init`` to ``/sbin/init.orig`` and
+  place generated init under original name, i.e. ``/sbin/init``. It has an advantage
+  that you won't need to change any kernel parameters in order to make it work,
+  but it poses a restriction that package-management can't be used, becaause updating
+  init manager would remove generated script
+* If you are would like to keep original init as is, you can set::
+
+   OVERLAYFS_ETC_USE_ORIG_INIT_NAME = "0"
+
+  Then generated init will be named ``/sbin/preinit`` and you would need to extend your
+  kernel parameters manually in your bootloader configuration.
 
 .. _ref-classes-own-mirrors:
 
-- 
2.28.0

[PATCH 2/2] ref-manual: document overlayfs-etc image feature

[Vyacheslav Yurkov]

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

diff --git a/documentation/ref-manual/features.rst b/documentation/ref-manual/features.rst
index ded653221..5f6c00fac 100644
--- a/documentation/ref-manual/features.rst
+++ b/documentation/ref-manual/features.rst
@@ -219,6 +219,10 @@ Here are the image features available for all images:
 -  *empty-root-password:* Sets the root password to an empty string,
    which allows logins with a blank password.
 
+-  *overlayfs-etc:* Configures ``/etc`` directory to be in ``overlayfs``.
+   This allows to store device specific information elsewhere, especially
+   if rootfs is configured to be read-only.
+
 -  *package-management:* Installs package management tools and preserves
    the package manager database.
 
-- 
2.28.0

Re: [docs] [PATCH 1/2] ref-manual: add overlayfs-etc class

[Michael Opdenacker]

Hi Slava,

Thanks for the documentation update patch!
See my comments below.

On 12/15/21 6:11 PM, Vyacheslav Yurkov wrote:
> Signed-off-by: Vyacheslav Yurkov <uvv.mail@gmail.com>
> ---
>  documentation/ref-manual/classes.rst | 41 ++++++++++++++++++++++++++++
>  1 file changed, 41 insertions(+)
>
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index 2c191f407..a5b01c2cf 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -1769,6 +1769,47 @@ to the unit the following::
>  .. note::
>  
>     The class does not support the ``/etc`` directory itself, because ``systemd`` depends on it.
> +   In order to get ``/etc`` in overlayfs see :ref:`overlayfs-etc <ref-classes-overlayfs-etc>` 
> +
> +.. _ref-classes-overlayfs-etc:
> +
> +``overlayfs-etc.bbclass``
> +=========================
> +
> +In order to have ``/etc`` directory in overlayfs a special handling at early 

s/to have/to have the/

> +boot stage is required.  The idea is to supply a custom init script that mounts
> +``/etc`` before launching actual init program, because the latter already


s/actual init program/the actual init program/

> +requires ``/etc`` to be mounted
> +
> +.. note::
> +
> +   This class must not be inherited directly. Use corresponding IMAGE_FEATURE
Oops, you forgot the "S" in "IMAGE_FEATURES". You may say:

Use :term:`IMAGE_FEATURES` or :term:`EXTRA_IMAGE_FEATURES`.

What about directly adding an example too?
> +
> +Your machine configuration should define at least device, mount point, and file system type
> +you are going to use for ``overlayfs``::


s/at least device/at least the device/

> +
> +  OVERLAYFS_ETC_MOUNT_POINT = "/data"
> +  OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2"
> +  OVERLAYFS_ETC_FSTYPE ?= "ext4"
> +
> +To control more mount options you should consider setting mount options
> +(``defaults`` is used by default)::
> +
> +  OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync"
> +
> +The class provides two options for ``/sbin/init`` generation:
> +
> +* Default option is to rename original ``/sbin/init`` to ``/sbin/init.orig`` and

s/Default/The default/

s/original/the original/

> +  place generated init under original name, i.e. ``/sbin/init``. It has an advantage

s/generated init/the generated init/

s/original name/its original name/

> +  that you won't need to change any kernel parameters in order to make it work,
> +  but it poses a restriction that package-management can't be used, becaause updating


s/becaause/because/

> +  init manager would remove generated script


s/generated script/the generated script/

> +* If you are would like to keep original init as is, you can set::


s/If you are would like/If you wish/

> +
> +   OVERLAYFS_ETC_USE_ORIG_INIT_NAME = "0"
> +
> +  Then generated init will be named ``/sbin/preinit`` and you would need to extend your


/s/generated init/the generated init/

Cheers
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH 2/2] ref-manual: document overlayfs-etc image feature

[Michael Opdenacker]

On 12/15/21 6:11 PM, Vyacheslav Yurkov wrote:
> Signed-off-by: Vyacheslav Yurkov <uvv.mail@gmail.com>
> ---
>  documentation/ref-manual/features.rst | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/documentation/ref-manual/features.rst b/documentation/ref-manual/features.rst
> index ded653221..5f6c00fac 100644
> --- a/documentation/ref-manual/features.rst
> +++ b/documentation/ref-manual/features.rst
> @@ -219,6 +219,10 @@ Here are the image features available for all images:
>  -  *empty-root-password:* Sets the root password to an empty string,
>     which allows logins with a blank password.
>  
> +-  *overlayfs-etc:* Configures ``/etc`` directory to be in ``overlayfs``.


/s/Configures/Configures the/

> +   This allows to store device specific information elsewhere, especially
> +   if rootfs is configured to be read-only.

s/rootfs/the root filesystem/

I'll propose a guideline to replace "rootfs" by "root filesystem", but
the way. Everyone understands this term here of course, but that's
better English ;-)

Thanks for the patch, and thanks in advance for the V2 ;)
Cheers
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH 1/2] ref-manual: add overlayfs-etc class

[Quentin Schulz]

Hi Vyacheslav,

On December 15, 2021 6:11:37 PM GMT+01:00, Vyacheslav Yurkov <uvv.mail@gmail.com> wrote:
>Signed-off-by: Vyacheslav Yurkov <uvv.mail@gmail.com>
>---
> documentation/ref-manual/classes.rst | 41 ++++++++++++++++++++++++++++
> 1 file changed, 41 insertions(+)
>
>diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
>index 2c191f407..a5b01c2cf 100644
>--- a/documentation/ref-manual/classes.rst
>+++ b/documentation/ref-manual/classes.rst
>@@ -1769,6 +1769,47 @@ to the unit the following::
> .. note::
> 
>    The class does not support the ``/etc`` directory itself, because ``systemd`` depends on it.
>+   In order to get ``/etc`` in overlayfs see :ref:`overlayfs-etc <ref-classes-overlayfs-etc>` 
>+

Missing dot at the end of the sentence.

>+.. _ref-classes-overlayfs-etc:
>+
>+``overlayfs-etc.bbclass``
>+=========================
>+
>+In order to have ``/etc`` directory in overlayfs a special handling at early 
>+boot stage is required.  The idea is to supply a custom init script that mounts
>+``/etc`` before launching actual init program, because the latter already
>+requires ``/etc`` to be mounted
>+

Missing dot at the end of the sentence.

>+.. note::
>+
>+   This class must not be inherited directly. Use corresponding IMAGE_FEATURE
>+

Missing dot at the end of the sentence.

>+Your machine configuration should define at least device, mount point, and file system type
>+you are going to use for ``overlayfs``::
>+
>+  OVERLAYFS_ETC_MOUNT_POINT = "/data"
>+  OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2"
>+  OVERLAYFS_ETC_FSTYPE ?= "ext4"
>+
>+To control more mount options you should consider setting mount options
>+(``defaults`` is used by default)::
>+
>+  OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync"
>+
>+The class provides two options for ``/sbin/init`` generation:
>+
>+* Default option is to rename original ``/sbin/init`` to ``/sbin/init.orig`` and
>+  place generated init under original name, i.e. ``/sbin/init``. It has an advantage
>+  that you won't need to change any kernel parameters in order to make it work,
>+  but it poses a restriction that package-management can't be used, becaause updating
>+  init manager would remove generated script

What is the default value? This needs to be explicit otherwise it cannot be "undone" in a bbappends for example.

Thanks for the patch,
Cheers,
Quentin

>+* If you are would like to keep original init as is, you can set::
>+
>+   OVERLAYFS_ETC_USE_ORIG_INIT_NAME = "0"
>+
>+  Then generated init will be named ``/sbin/preinit`` and you would need to extend your
>+  kernel parameters manually in your bootloader configuration.
> 
> .. _ref-classes-own-mirrors:
> 

Re: [docs] [PATCH 1/2] ref-manual: add overlayfs-etc class

[Vyacheslav Yurkov]

Hi Quentin,
Thanks for the review

On 16.12.2021 18:37, Quentin Schulz wrote:
>
>> +
>> +  OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync"
>> +
>> +The class provides two options for ``/sbin/init`` generation:
>> +
>> +* Default option is to rename original ``/sbin/init`` to ``/sbin/init.orig`` and
>> +  place generated init under original name, i.e. ``/sbin/init``. It has an advantage
>> +  that you won't need to change any kernel parameters in order to make it work,
>> +  but it poses a restriction that package-management can't be used, becaause updating
>> +  init manager would remove generated script
> What is the default value? This needs to be explicit otherwise it cannot be "undone" in a bbappends for example.
>
> Thanks for the patch,
> Cheers,
> Quentin

Could you please elaborate on default value of what we are talking here? 
For mandatory variables there are no default values, for two optional 
variables the default values are set with ??=.

Cheers,
Slava