From 99980546fa5482447bebb6ab0a1bd5c7a4148157 Mon Sep 17 00:00:00 2001
From: Scott Rifenbark <srifenbark@gmail.com>
Date: Thu, 11 Jan 2018 11:17:06 -0800
Subject: overview-manual, ref-manual: Moved Pseudo and Fakeroot to overview
 manual

Fixes [YOCTO #12370]

The "Fakeroot and Pseudo" section is concepts and needed moved from the
ref-manual to the new concepts chapter of the overview-manual.  Some
links needed to be fixed as well.

(From yocto-docs rev: df2c09407abd5ca468fcd0bd9e241739907a9d63)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 .../overview-manual/overview-concepts.xml          | 72 ++++++++++++++++++++++
 1 file changed, 72 insertions(+)

(limited to 'documentation/overview-manual')

diff --git a/documentation/overview-manual/overview-concepts.xml b/documentation/overview-manual/overview-concepts.xml
index 9fb3283fee..74ce7fd52f 100644
--- a/documentation/overview-manual/overview-concepts.xml
+++ b/documentation/overview-manual/overview-concepts.xml
@@ -1253,6 +1253,78 @@
         </para>
     </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
+            <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
+            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><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><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 psABI</title>
 
-- 
cgit v1.2.3-54-g00ecf