Merge pull request rauc#1192 from jluebbe/doc-faq-ext4

docs/faq: document possible filesystem incompatibility with ext4

docs/faq.rst

@@ -164,3 +164,40 @@ something like::
 Custom udev rules can also be very useful when you want to refer to the active
 data partition (in a scenario with redundant data partitions) with a fixed
 name.
+
+Why does the installation fail with a ``resize2fs`` error?
+----------------------------------------------------------
+
+When installing a ext4 image with ``resize=true`` configured for that slot, it
+may happen that the ext4 image has features enabled which are not supported by
+the currently used version of ``resize2fs``.
+
+For example, ``e2fstools`` 1.47 enabled the ``orphan_file`` feature by default
+and is included in Yocto mickledore.
+When an image generated by Yocto mickledore is installed on an older release
+(perhaps built using kirkstone or older), that version of ``resize2fs`` will
+refuse to modify the filesystem and the installation will be aborted::
+
+  LastError: Installation error: Failed updating slot rootfs.1: Failed to run resize2fs: Child process exited with code 1
+
+In the log output from RAUC, you'll find more details::
+
+  …
+  rauc[409]: opening slot device /dev/mmcblk0p2
+  rauc[409]: writing data to device /dev/mmcblk0p2
+  rauc[409]: Resizing /dev/mmcblk0p2
+  …
+  rauc[551]: resize2fs 1.46.5 (30-Dec-2021)
+  rauc[551]: resize2fs: Filesystem has unsupported feature(s) (/dev/mmcblk0p2)
+  rauc[409]: Installation error: Failed updating slot rootfs.1: Failed to run resize2fs: Child process exited with code 1
+  …
+
+The solution for this is to disable the unsupported filesystem features during
+the image generation.
+When using Yocto, in case of the ``orphan_file`` file feature, you could use::
+
+  EXTRA_IMAGECMD:ext4:append = " -O ^orphan_file"
+
+in the image recipe or an appropriate conf file to disable the feature until
+all systems have been updated with versions of ``resize2fs`` which support this
+feature.