diff options
| -rw-r--r-- | documentation/ref-manual/ref-tasks.xml | 9 | ||||
| -rw-r--r-- | documentation/ref-manual/ref-variables.xml | 5 | ||||
| -rw-r--r-- | documentation/ref-manual/technical-details.xml | 72 |
3 files changed, 86 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml index d6f0051f16..b0a65a989b 100644 --- a/documentation/ref-manual/ref-tasks.xml +++ b/documentation/ref-manual/ref-tasks.xml @@ -260,6 +260,15 @@ This task runs with the current working directory set to <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>, which is the compilation directory. + The <filename>do_install</filename> task, as well as other tasks + that either directly or indirectly depend on the installed files + (e.g. + <link linkend='ref-tasks-package'><filename>do_package</filename></link>, + <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>, + and + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>), + run under + <link linkend='fakeroot-and-pseudo'>fakeroot</link>. <note> <title>Caution</title> diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml index 3fe5cc3c2d..2507d4b520 100644 --- a/documentation/ref-manual/ref-variables.xml +++ b/documentation/ref-manual/ref-variables.xml @@ -2599,6 +2599,11 @@ <literallayout class='monospaced'> ${<link linkend='var-WORKDIR'>WORKDIR</link>}/image </literallayout> + <note><title>Caution</title> + Tasks that read from or write to this directory should + run under + <link linkend='fakeroot-and-pseudo'>fakeroot</link>. + </note> </para> </glossdef> </glossentry> diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml index 8535d2c6e8..5ef764c8e0 100644 --- a/documentation/ref-manual/technical-details.xml +++ b/documentation/ref-manual/technical-details.xml @@ -1020,6 +1020,78 @@ </section> </section> +<section id='fakeroot-and-pseudo'> + <title>Fakeroot and Pseudo</title> + + <para> + Some tasks are easier to implement when allowed to perform certain + operations that are normally reserved for the root user. + For example, the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task benefits from being able to set the UID and GID of installed files + to arbitrary values. + </para> + + <para> + One approach to allowing tasks to perform root-only operations + would be to require BitBake to run as root. + However, this method is cumbersome and has security issues. + The approach that is actually used is to run tasks that benefit from + root privileges in a "fake" root environment. + Within this environment, the task and its child processes believe that + they are running as the root user, and see an internally consistent + view of the filesystem. + As long as generating the final output (e.g. a package or an image) + does not require root privileges, the fact that some earlier steps ran + in a fake root environment does not cause problems. + </para> + + <para> + The capability to run tasks in a fake root environment is known as + "fakeroot", which is derived from the BitBake keyword/variable + flag that requests a fake root environment for a task. + In current versions of the OpenEmbedded build system, + the program that implements fakeroot is known as Pseudo. + </para> + + <para> + Pseudo overrides system calls through the + <filename>LD_PRELOAD</filename> mechanism to give the + illusion of running as root. + To keep track of "fake" file ownership and permissions resulting from + operations that require root permissions, an sqlite3 + database is used. + This database is stored in + <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/pseudo/files.db</filename> + for individual recipes. + Storing the database in a file as opposed to in memory + gives persistence between tasks, and even between builds. + <note><title>Caution</title> + If you add your own task that manipulates the same files or + directories as a fakeroot task, then that task should also run + under fakeroot. + Otherwise, the task will not be able to run root-only operations, + and will not see the fake file ownership and permissions set by the + other task. + You should also add a dependency on + <filename>virtual/fakeroot-native:do_populate_sysroot</filename>, + giving the following: + <literallayout class='monospaced'> + fakeroot do_mytask () { + ... + } + do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" + </literallayout> + </note> + For more information, see the + <ulink url='&YOCTO_DOCS_BB_URL;#var-FAKEROOT'><filename>FAKEROOT*</filename></ulink> + variables in the BitBake User Manual. + You can also reference this + <ulink url='http://www.ibm.com/developerworks/opensource/library/os-aapseudo1/index.html'>Pseudo</ulink> + article. + </para> +</section> + <section id='x32'> <title>x32</title> |