diff options
Diffstat (limited to 'documentation/dev-manual/read-only-rootfs.rst')
-rw-r--r-- | documentation/dev-manual/read-only-rootfs.rst | 89 |
1 files changed, 89 insertions, 0 deletions
diff --git a/documentation/dev-manual/read-only-rootfs.rst b/documentation/dev-manual/read-only-rootfs.rst new file mode 100644 index 0000000000..251178ed54 --- /dev/null +++ b/documentation/dev-manual/read-only-rootfs.rst | |||
@@ -0,0 +1,89 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | Creating a Read-Only Root Filesystem | ||
4 | ************************************ | ||
5 | |||
6 | Suppose, for security reasons, you need to disable your target device's | ||
7 | root filesystem's write permissions (i.e. you need a read-only root | ||
8 | filesystem). Or, perhaps you are running the device's operating system | ||
9 | from a read-only storage device. For either case, you can customize your | ||
10 | image 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 | |||
20 | Creating the Root Filesystem | ||
21 | ============================ | ||
22 | |||
23 | To create the read-only root filesystem, simply add the | ||
24 | "read-only-rootfs" feature to your image, normally in one of two ways. | ||
25 | The first way is to add the "read-only-rootfs" image feature in the | ||
26 | image's recipe file via the :term:`IMAGE_FEATURES` variable:: | ||
27 | |||
28 | IMAGE_FEATURES += "read-only-rootfs" | ||
29 | |||
30 | As an alternative, you can add the same feature | ||
31 | from within your :term:`Build Directory`'s ``local.conf`` file with the | ||
32 | associated :term:`EXTRA_IMAGE_FEATURES` variable, as in:: | ||
33 | |||
34 | EXTRA_IMAGE_FEATURES = "read-only-rootfs" | ||
35 | |||
36 | For 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\`\``" | ||
38 | section. For information on the variables, see | ||
39 | :term:`IMAGE_FEATURES` and | ||
40 | :term:`EXTRA_IMAGE_FEATURES`. | ||
41 | |||
42 | Post-Installation Scripts and Read-Only Root Filesystem | ||
43 | ======================================================= | ||
44 | |||
45 | It is very important that you make sure all post-Installation | ||
46 | (``pkg_postinst``) scripts for packages that are installed into the | ||
47 | image can be run at the time when the root filesystem is created during | ||
48 | the build on the host system. These scripts cannot attempt to run during | ||
49 | the first boot on the target device. With the "read-only-rootfs" feature | ||
50 | enabled, the build system makes sure that all post-installation scripts | ||
51 | succeed at file system creation time. If any of these scripts | ||
52 | still need to be run after the root filesystem is created, the build | ||
53 | immediately fails. These build-time checks ensure that the build fails | ||
54 | rather than the target device fails later during its initial boot | ||
55 | operation. | ||
56 | |||
57 | Most of the common post-installation scripts generated by the build | ||
58 | system for the out-of-the-box Yocto Project are engineered so that they | ||
59 | can run during root filesystem creation (e.g. post-installation scripts | ||
60 | for caching fonts). However, if you create and add custom scripts, you | ||
61 | need to be sure they can be run during this file system creation. | ||
62 | |||
63 | Here are some common problems that prevent post-installation scripts | ||
64 | from 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 | |||
81 | Areas With Write Access | ||
82 | ======================= | ||
83 | |||
84 | With the "read-only-rootfs" feature enabled, any attempt by the target | ||
85 | to write to the root filesystem at runtime fails. Consequently, you must | ||
86 | make sure that you configure processes and applications that attempt | ||
87 | these types of writes do so to directories with write access (e.g. | ||
88 | ``/tmp`` or ``/var/run``). | ||
89 | |||