.. SPDX-License-Identifier: CC-BY-SA-2.0-UK

Creating a Read-Only Root Filesystem
************************************

Suppose, for security reasons, you need to disable your target device's
root filesystem's write permissions (i.e. you need a read-only root
filesystem). Or, perhaps you are running the device's operating system
from a read-only storage device. For either case, you can customize your
image for that behavior.

.. note::

   Supporting a read-only root filesystem requires that the system and
   applications do not try to write to the root filesystem. You must
   configure all parts of the target system to write elsewhere, or to
   gracefully fail in the event of attempting to write to the root
   filesystem.

Creating the Root Filesystem
============================

To create the read-only root filesystem, simply add the
"read-only-rootfs" feature to your image, normally in one of two ways.
The first way is to add the "read-only-rootfs" image feature in the
image's recipe file via the :term:`IMAGE_FEATURES` variable::

   IMAGE_FEATURES += "read-only-rootfs"

As an alternative, you can add the same feature
from within your :term:`Build Directory`'s ``local.conf`` file with the
associated :term:`EXTRA_IMAGE_FEATURES` variable, as in::

   EXTRA_IMAGE_FEATURES = "read-only-rootfs"

For more information on how to use these variables, see the
":ref:`dev-manual/customizing-images:Customizing Images Using Custom \`\`IMAGE_FEATURES\`\` and \`\`EXTRA_IMAGE_FEATURES\`\``"
section. For information on the variables, see
:term:`IMAGE_FEATURES` and
:term:`EXTRA_IMAGE_FEATURES`.

Post-Installation Scripts and Read-Only Root Filesystem
=======================================================

It is very important that you make sure all post-Installation
(``pkg_postinst``) scripts for packages that are installed into the
image can be run at the time when the root filesystem is created during
the build on the host system. These scripts cannot attempt to run during
the first boot on the target device. With the "read-only-rootfs" feature
enabled, the build system makes sure that all post-installation scripts
succeed at file system creation time. If any of these scripts
still need to be run after the root filesystem is created, the build
immediately fails. These build-time checks ensure that the build fails
rather than the target device fails later during its initial boot
operation.

Most of the common post-installation scripts generated by the build
system for the out-of-the-box Yocto Project are engineered so that they
can run during root filesystem creation (e.g. post-installation scripts
for caching fonts). However, if you create and add custom scripts, you
need to be sure they can be run during this file system creation.

Here are some common problems that prevent post-installation scripts
from running during root filesystem creation:

-  *Not using $D in front of absolute paths:* The build system defines
   ``$``\ :term:`D` when the root
   filesystem is created. Furthermore, ``$D`` is blank when the script
   is run on the target device. This implies two purposes for ``$D``:
   ensuring paths are valid in both the host and target environments,
   and checking to determine which environment is being used as a method
   for taking appropriate actions.

-  *Attempting to run processes that are specific to or dependent on the
   target architecture:* You can work around these attempts by using
   native tools, which run on the host system, to accomplish the same
   tasks, or by alternatively running the processes under QEMU, which
   has the ``qemu_run_binary`` function. For more information, see the
   :ref:`ref-classes-qemu` class.

Areas With Write Access
=======================

With the "read-only-rootfs" feature enabled, any attempt by the target
to write to the root filesystem at runtime fails. Consequently, you must
make sure that you configure processes and applications that attempt
these types of writes do so to directories with write access (e.g.
``/tmp`` or ``/var/run``).