From 3ccd6fde214b4514cc5cf68f8020bbcb355581a4 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 5 Apr 2013 06:13:13 -0700 Subject: [PATCH] dev-manual: Changes to the read-only root filesystem section. Applied the review comments from Paul Eggleton to augment this section with more information. Performed a spell check on the entire chapter. Made the term "postinstall" consistent by defining its first use in sections a "post-installation (postinstall) script". (From yocto-docs rev: 179f478777fd02e3fa56d80951ce3eab350fc189) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 148 ++++++++++++++---- 1 file changed, 118 insertions(+), 30 deletions(-) diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 70ecc2276a..f8b41bf54d 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -1022,10 +1022,11 @@
- Post Install Scripts + Post-Installation Scripts - To add a post-installation script to a package, add a pkg_postinst_PACKAGENAME() + To add a post-installation (postinstall) script to a package, + add a pkg_postinst_PACKAGENAME() function to the .bb file and use PACKAGENAME as the name of the package you want to attach to the postinst script. @@ -1488,7 +1489,7 @@ These situations almost always exist when a library API changes and you have multiple pieces of software that depend on the separate versions of the library. - To accomodate these situations, you can install multiple + To accommodate these situations, you can install multiple versions of the same library in parallel on the same system. @@ -2297,7 +2298,7 @@ your own distribution. You can use the Yocto Project out-of-the-box to create the poky-tiny distribution. - Ulitmately, you will want to make changes in your own + Ultimately, you will want to make changes in your own distribution that are likely modeled after poky-tiny. @@ -2870,7 +2871,7 @@ If you have more than one distribution alias, separate them with a space. Note that the build system currently automatically checks the - Fedora, OpenSuSE, Debian, Ubuntu, + Fedora, OpenSUSE, Debian, Ubuntu, and Mandriva distributions for source package recipes without having to specify them using the DISTRO_PN_ALIAS variable. For example, the following command generates a report that lists the Linux distributions @@ -3447,8 +3448,8 @@ Creating a Read-Only Root Filesystem - Suppose, for security reasons, you need to disable the - your target device's root filesystem's write permisions + 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. @@ -3456,34 +3457,121 @@ that behavior. - - To create a read-only root filesystem, simply add the - "read-only-rootfs" feature to your image. - Using either of the following statements in your - image recipe or from within the - local.conf file found in the Build - Directory causes the build system to create a - read-only root filesystem: - + + Supporting a read-only root filesystem requires that the system and + applications do not try to write to the root filesystem. + If writes are attempted, they need to gracefully fail. + + +
+ Post-Installation Scripts + + + It is very important that you make sure all + Post-Installation (postinstall) 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 first-boot on the + target device. + With the read-only root filesystem feature enabled, + the build system checks during root filesystem creation to make + sure all postinstall scripts succeed. + If any of these scripts still need to be run after the root + filesystem is created, the build immediately fails. + These checks during build time ensure that the build fails + rather than the target device fails later during its + initial boot operation. + + + + Most of the common postinstall 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. postinstall scripts for caching fonts). + However, if you create and add custom scripts, you need + to be sure they can be run during file system creation. + + + + Here are some common problems that prevent postinstall + scripts from running during root filesystem creation: + + Not using + $D + in front of absolute paths. + The build system defines $D, and + it is blank when 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 to accomplish the same processes (tasks), or + by alternatively running the processes under QEMU, + which has the qemu_run_binary + function. + For more information, see the + meta/classes/qemu.bbclass + class in the + Source Directory. + + Using hardware features specific to the machine. + + + +
+ +
+ Areas With Write Access + + + With the read-only root filesystem 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 (i.e. + /tmp or /var/run). + +
+ +
+ Creating the Root Filesystem + + + To create the read-only root filesystem, simply add the + "read-only-rootfs" feature to your image. + Using either of the following statements in your + image recipe or from within the + local.conf file found in the + Build Directory + causes the build system to create a read-only root filesystem: + IMAGE_FEATURES = "read-only-rootfs" - - or - + + or + EXTRA_IMAGE_FEATURES = "read-only-rootfs" - - + + - - For more information on how to use these variables, see the - "Customizing Images Using Custom IMAGE_FEATURES and EXTRA_IMAGE_FEATURES" - section. - For information on the variables, see - IMAGE_FEATURES - and EXTRA_IMAGE_FEATURES. - + + For more information on how to use these variables, see the + "Customizing Images Using Custom IMAGE_FEATURES and EXTRA_IMAGE_FEATURES" + section. + For information on the variables, see + IMAGE_FEATURES + and EXTRA_IMAGE_FEATURES. + +
-
Debugging With the GNU Project Debugger (GDB) Remotely