1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3Creating a Read-Only Root Filesystem
4************************************
5
6Suppose, for security reasons, you need to disable your target device's
7root filesystem's write permissions (i.e. you need a read-only root
8filesystem). Or, perhaps you are running the device's operating system
9from a read-only storage device. For either case, you can customize your
10image for that behavior.
11
12.. note::
13
14   Supporting a read-only root filesystem requires that the system and
15   applications do not try to write to the root filesystem. You must
16   configure all parts of the target system to write elsewhere, or to
17   gracefully fail in the event of attempting to write to the root
18   filesystem.
19
20Creating the Root Filesystem
21============================
22
23To create the read-only root filesystem, simply add the
24"read-only-rootfs" feature to your image, normally in one of two ways.
25The first way is to add the "read-only-rootfs" image feature in the
26image's recipe file via the :term:`IMAGE_FEATURES` variable::
27
28   IMAGE_FEATURES += "read-only-rootfs"
29
30As an alternative, you can add the same feature
31from within your :term:`Build Directory`'s ``local.conf`` file with the
32associated :term:`EXTRA_IMAGE_FEATURES` variable, as in::
33
34   EXTRA_IMAGE_FEATURES = "read-only-rootfs"
35
36For more information on how to use these variables, see the
37":ref:`dev-manual/customizing-images:Customizing Images Using Custom \`\`IMAGE_FEATURES\`\` and \`\`EXTRA_IMAGE_FEATURES\`\``"
38section. For information on the variables, see
39:term:`IMAGE_FEATURES` and
40:term:`EXTRA_IMAGE_FEATURES`.
41
42Post-Installation Scripts and Read-Only Root Filesystem
43=======================================================
44
45It is very important that you make sure all post-Installation
46(``pkg_postinst``) scripts for packages that are installed into the
47image can be run at the time when the root filesystem is created during
48the build on the host system. These scripts cannot attempt to run during
49the first boot on the target device. With the "read-only-rootfs" feature
50enabled, the build system makes sure that all post-installation scripts
51succeed at file system creation time. If any of these scripts
52still need to be run after the root filesystem is created, the build
53immediately fails. These build-time checks ensure that the build fails
54rather than the target device fails later during its initial boot
55operation.
56
57Most of the common post-installation scripts generated by the build
58system for the out-of-the-box Yocto Project are engineered so that they
59can run during root filesystem creation (e.g. post-installation scripts
60for caching fonts). However, if you create and add custom scripts, you
61need to be sure they can be run during this file system creation.
62
63Here are some common problems that prevent post-installation scripts
64from running during root filesystem creation:
65
66-  *Not using $D in front of absolute paths:* The build system defines
67   ``$``\ :term:`D` when the root
68   filesystem is created. Furthermore, ``$D`` is blank when the script
69   is run on the target device. This implies two purposes for ``$D``:
70   ensuring paths are valid in both the host and target environments,
71   and checking to determine which environment is being used as a method
72   for taking appropriate actions.
73
74-  *Attempting to run processes that are specific to or dependent on the
75   target architecture:* You can work around these attempts by using
76   native tools, which run on the host system, to accomplish the same
77   tasks, or by alternatively running the processes under QEMU, which
78   has the ``qemu_run_binary`` function. For more information, see the
79   :ref:`ref-classes-qemu` class.
80
81Areas With Write Access
82=======================
83
84With the "read-only-rootfs" feature enabled, any attempt by the target
85to write to the root filesystem at runtime fails. Consequently, you must
86make sure that you configure processes and applications that attempt
87these types of writes do so to directories with write access (e.g.
88``/tmp`` or ``/var/run``).
89
90