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 @@ +
+ Fakeroot and Pseudo + + + Some tasks are easier to implement when allowed to perform certain + operations that are normally reserved for the root user. + For example, the + do_install + task benefits from being able to set the UID and GID of installed + files to arbitrary values. + + + + 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. + + + + 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. + + + + Pseudo overrides system calls through the + LD_PRELOAD 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 + ${WORKDIR}/pseudo/files.db + for individual recipes. + Storing the database in a file as opposed to in memory + gives persistence between tasks, and even between builds. + Caution + 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 + virtual/fakeroot-native:do_populate_sysroot, + giving the following: + + fakeroot do_mytask () { + ... + } + do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" + + + For more information, see the + FAKEROOT* + variables in the BitBake User Manual. + You can also reference this + Pseudo + article. + +
+
x32 psABI diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml index 0909595834..4fa64c0d60 100644 --- a/documentation/ref-manual/ref-tasks.xml +++ b/documentation/ref-manual/ref-tasks.xml @@ -268,7 +268,7 @@ and do_rootfs), run under - fakeroot. + fakeroot. Caution diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml index 67cf8859ee..a971e2a8f9 100644 --- a/documentation/ref-manual/ref-variables.xml +++ b/documentation/ref-manual/ref-variables.xml @@ -3016,7 +3016,7 @@ Caution Tasks that read from or write to this directory should run under - fakeroot. + fakeroot. diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml index b30dfe8597..2b4f2d933c 100644 --- a/documentation/ref-manual/technical-details.xml +++ b/documentation/ref-manual/technical-details.xml @@ -13,78 +13,6 @@ x32, Wayland support, and Licenses. -
- Fakeroot and Pseudo - - - Some tasks are easier to implement when allowed to perform certain - operations that are normally reserved for the root user. - For example, the - do_install - task benefits from being able to set the UID and GID of installed files - to arbitrary values. - - - - 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. - - - - 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. - - - - Pseudo overrides system calls through the - LD_PRELOAD 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 - ${WORKDIR}/pseudo/files.db - for individual recipes. - Storing the database in a file as opposed to in memory - gives persistence between tasks, and even between builds. - Caution - 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 - virtual/fakeroot-native:do_populate_sysroot, - giving the following: - - fakeroot do_mytask () { - ... - } - do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" - - - For more information, see the - FAKEROOT* - variables in the BitBake User Manual. - You can also reference this - Pseudo - article. - -
-
Wayland diff --git a/documentation/yocto-project-qs/qs.xml b/documentation/yocto-project-qs/qs.xml index dda3c112ea..3c61b9b499 100644 --- a/documentation/yocto-project-qs/qs.xml +++ b/documentation/yocto-project-qs/qs.xml @@ -1088,8 +1088,8 @@ I don't have much on this in the manual set. Is there any more information we can leverage? For information on Fakeroot and Pseudo, see the - "Fakeroot and Pseudo" - section in the Yocto Project Reference Manual. + "Fakeroot and Pseudo" + section in the Yocto Project Overview Manual. OPKG: