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 <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
Richard Purdie
parent
46a05ed934
commit
3ccd6fde21
|
|
@ -1022,10 +1022,11 @@
|
|||
</section>
|
||||
|
||||
<section id='usingpoky-extend-addpkg-postinstalls'>
|
||||
<title>Post Install Scripts</title>
|
||||
<title>Post-Installation Scripts</title>
|
||||
|
||||
<para>
|
||||
To add a post-installation script to a package, add a <filename>pkg_postinst_PACKAGENAME()
|
||||
To add a post-installation (postinstall) script to a package,
|
||||
add a <filename>pkg_postinst_PACKAGENAME()
|
||||
</filename> function to the <filename>.bb</filename> file and use
|
||||
<filename>PACKAGENAME</filename> as the name of the package you want to attach to the
|
||||
<filename>postinst</filename> 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.
|
||||
</para>
|
||||
|
||||
|
|
@ -2297,7 +2298,7 @@
|
|||
your own distribution.
|
||||
You can use the Yocto Project out-of-the-box to create the
|
||||
<filename>poky-tiny</filename> 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
|
||||
<filename>poky-tiny</filename>.
|
||||
<note>
|
||||
|
|
@ -2870,7 +2871,7 @@
|
|||
<para>
|
||||
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 <filename>DISTRO_PN_ALIAS</filename> variable.
|
||||
For example, the following command generates a report that lists the Linux distributions
|
||||
|
|
@ -3447,8 +3448,8 @@
|
|||
<title>Creating a Read-Only Root Filesystem</title>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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
|
||||
<filename>local.conf</filename> file found in the Build
|
||||
Directory causes the build system to create a
|
||||
read-only root filesystem:
|
||||
<literallayout class='monospaced'>
|
||||
<note>
|
||||
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.
|
||||
</note>
|
||||
|
||||
<section id='post-installation-scripts'>
|
||||
<title>Post-Installation Scripts</title>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Here are some common problems that prevent postinstall
|
||||
scripts from running during root filesystem creation:
|
||||
<itemizedlist>
|
||||
<listitem><para>Not using
|
||||
<filename>$</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
|
||||
in front of absolute paths.
|
||||
The build system defines <filename>$D</filename>, and
|
||||
it is blank when run on the target device.
|
||||
This implies two purposes for <filename>$D</filename>:
|
||||
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.
|
||||
</para></listitem>
|
||||
<listitem><para>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 <filename>qemu_run_binary</filename>
|
||||
function.
|
||||
For more information, see the
|
||||
<filename>meta/classes/qemu.bbclass</filename>
|
||||
class in the
|
||||
<link linkend='source-directory'>Source Directory</link>.
|
||||
</para></listitem>
|
||||
<listitem><para>Using hardware features specific to the machine.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='areas-with-write-access'>
|
||||
<title>Areas With Write Access</title>
|
||||
|
||||
<para>
|
||||
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.
|
||||
<filename>/tmp</filename> or <filename>/var/run</filename>).
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='creating-the-root-filesystem'>
|
||||
<title>Creating the Root Filesystem</title>
|
||||
|
||||
<para>
|
||||
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
|
||||
<filename>local.conf</filename> file found in the
|
||||
<link linkend='build-directory'>Build Directory</link>
|
||||
causes the build system to create a read-only root filesystem:
|
||||
<literallayout class='monospaced'>
|
||||
IMAGE_FEATURES = "read-only-rootfs"
|
||||
</literallayout>
|
||||
or
|
||||
<literallayout class='monospaced'>
|
||||
</literallayout>
|
||||
or
|
||||
<literallayout class='monospaced'>
|
||||
EXTRA_IMAGE_FEATURES = "read-only-rootfs"
|
||||
</literallayout>
|
||||
</para>
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For more information on how to use these variables, see the
|
||||
"<link linkend='usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></link>"
|
||||
section.
|
||||
For information on the variables, see
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
|
||||
and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>.
|
||||
</para>
|
||||
<para>
|
||||
For more information on how to use these variables, see the
|
||||
"<link linkend='usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></link>"
|
||||
section.
|
||||
For information on the variables, see
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
|
||||
and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
|
||||
<section id="platdev-gdb-remotedebug">
|
||||
<title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue