diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2018-01-11 11:17:06 -0800 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2018-02-14 15:25:28 +0000 |
commit | 99980546fa5482447bebb6ab0a1bd5c7a4148157 (patch) | |
tree | d55b413650de4d55ac60d5accd443a45f200e4c6 | |
parent | a60d9e29171eaf73dc5ce70fdd2ce92ec07876ec (diff) | |
download | poky-99980546fa5482447bebb6ab0a1bd5c7a4148157.tar.gz |
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>
-rw-r--r-- | documentation/overview-manual/overview-concepts.xml | 72 | ||||
-rw-r--r-- | documentation/ref-manual/ref-tasks.xml | 2 | ||||
-rw-r--r-- | documentation/ref-manual/ref-variables.xml | 2 | ||||
-rw-r--r-- | documentation/ref-manual/technical-details.xml | 72 | ||||
-rw-r--r-- | documentation/yocto-project-qs/qs.xml | 4 |
5 files changed, 76 insertions, 76 deletions
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 @@ | |||
1253 | </para> | 1253 | </para> |
1254 | </section> | 1254 | </section> |
1255 | 1255 | ||
1256 | <section id='fakeroot-and-pseudo'> | ||
1257 | <title>Fakeroot and Pseudo</title> | ||
1258 | |||
1259 | <para> | ||
1260 | Some tasks are easier to implement when allowed to perform certain | ||
1261 | operations that are normally reserved for the root user. | ||
1262 | For example, the | ||
1263 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> | ||
1264 | task benefits from being able to set the UID and GID of installed | ||
1265 | files to arbitrary values. | ||
1266 | </para> | ||
1267 | |||
1268 | <para> | ||
1269 | One approach to allowing tasks to perform root-only operations | ||
1270 | would be to require BitBake to run as root. | ||
1271 | However, this method is cumbersome and has security issues. | ||
1272 | The approach that is actually used is to run tasks that benefit | ||
1273 | from root privileges in a "fake" root environment. | ||
1274 | Within this environment, the task and its child processes believe | ||
1275 | that they are running as the root user, and see an internally | ||
1276 | consistent view of the filesystem. | ||
1277 | As long as generating the final output (e.g. a package or an image) | ||
1278 | does not require root privileges, the fact that some earlier | ||
1279 | steps ran in a fake root environment does not cause problems. | ||
1280 | </para> | ||
1281 | |||
1282 | <para> | ||
1283 | The capability to run tasks in a fake root environment is known as | ||
1284 | "fakeroot", which is derived from the BitBake keyword/variable | ||
1285 | flag that requests a fake root environment for a task. | ||
1286 | In current versions of the OpenEmbedded build system, | ||
1287 | the program that implements fakeroot is known as Pseudo. | ||
1288 | </para> | ||
1289 | |||
1290 | <para> | ||
1291 | Pseudo overrides system calls through the | ||
1292 | <filename>LD_PRELOAD</filename> mechanism to give the | ||
1293 | illusion of running as root. | ||
1294 | To keep track of "fake" file ownership and permissions resulting | ||
1295 | from operations that require root permissions, an sqlite3 | ||
1296 | database is used. | ||
1297 | This database is stored in | ||
1298 | <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/pseudo/files.db</filename> | ||
1299 | for individual recipes. | ||
1300 | Storing the database in a file as opposed to in memory | ||
1301 | gives persistence between tasks, and even between builds. | ||
1302 | <note><title>Caution</title> | ||
1303 | If you add your own task that manipulates the same files or | ||
1304 | directories as a fakeroot task, then that task should also run | ||
1305 | under fakeroot. | ||
1306 | Otherwise, the task will not be able to run root-only | ||
1307 | operations, and will not see the fake file ownership and | ||
1308 | permissions set by the other task. | ||
1309 | You should also add a dependency on | ||
1310 | <filename>virtual/fakeroot-native:do_populate_sysroot</filename>, | ||
1311 | giving the following: | ||
1312 | <literallayout class='monospaced'> | ||
1313 | fakeroot do_mytask () { | ||
1314 | ... | ||
1315 | } | ||
1316 | do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" | ||
1317 | </literallayout> | ||
1318 | </note> | ||
1319 | For more information, see the | ||
1320 | <ulink url='&YOCTO_DOCS_BB_URL;#var-FAKEROOT'><filename>FAKEROOT*</filename></ulink> | ||
1321 | variables in the BitBake User Manual. | ||
1322 | You can also reference this | ||
1323 | <ulink url='http://www.ibm.com/developerworks/opensource/library/os-aapseudo1/index.html'>Pseudo</ulink> | ||
1324 | article. | ||
1325 | </para> | ||
1326 | </section> | ||
1327 | |||
1256 | <section id='x32'> | 1328 | <section id='x32'> |
1257 | <title>x32 psABI</title> | 1329 | <title>x32 psABI</title> |
1258 | 1330 | ||
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 @@ | |||
268 | and | 268 | and |
269 | <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>), | 269 | <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>), |
270 | run under | 270 | run under |
271 | <link linkend='fakeroot-and-pseudo'>fakeroot</link>. | 271 | <ulink url='&YOCTO_DOCS_OVERVIEW_URL;#fakeroot-and-pseudo'>fakeroot</ulink>. |
272 | <note> | 272 | <note> |
273 | <title>Caution</title> | 273 | <title>Caution</title> |
274 | 274 | ||
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 @@ | |||
3016 | <note><title>Caution</title> | 3016 | <note><title>Caution</title> |
3017 | Tasks that read from or write to this directory should | 3017 | Tasks that read from or write to this directory should |
3018 | run under | 3018 | run under |
3019 | <link linkend='fakeroot-and-pseudo'>fakeroot</link>. | 3019 | <ulink url='&YOCTO_DOCS_OVERVIEW_URL;#fakeroot-and-pseudo'>fakeroot</ulink>. |
3020 | </note> | 3020 | </note> |
3021 | </para> | 3021 | </para> |
3022 | </glossdef> | 3022 | </glossdef> |
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 @@ | |||
13 | x32, Wayland support, and Licenses. | 13 | x32, Wayland support, and Licenses. |
14 | </para> | 14 | </para> |
15 | 15 | ||
16 | <section id='fakeroot-and-pseudo'> | ||
17 | <title>Fakeroot and Pseudo</title> | ||
18 | |||
19 | <para> | ||
20 | Some tasks are easier to implement when allowed to perform certain | ||
21 | operations that are normally reserved for the root user. | ||
22 | For example, the | ||
23 | <link linkend='ref-tasks-install'><filename>do_install</filename></link> | ||
24 | task benefits from being able to set the UID and GID of installed files | ||
25 | to arbitrary values. | ||
26 | </para> | ||
27 | |||
28 | <para> | ||
29 | One approach to allowing tasks to perform root-only operations | ||
30 | would be to require BitBake to run as root. | ||
31 | However, this method is cumbersome and has security issues. | ||
32 | The approach that is actually used is to run tasks that benefit from | ||
33 | root privileges in a "fake" root environment. | ||
34 | Within this environment, the task and its child processes believe that | ||
35 | they are running as the root user, and see an internally consistent | ||
36 | view of the filesystem. | ||
37 | As long as generating the final output (e.g. a package or an image) | ||
38 | does not require root privileges, the fact that some earlier steps ran | ||
39 | in a fake root environment does not cause problems. | ||
40 | </para> | ||
41 | |||
42 | <para> | ||
43 | The capability to run tasks in a fake root environment is known as | ||
44 | "fakeroot", which is derived from the BitBake keyword/variable | ||
45 | flag that requests a fake root environment for a task. | ||
46 | In current versions of the OpenEmbedded build system, | ||
47 | the program that implements fakeroot is known as Pseudo. | ||
48 | </para> | ||
49 | |||
50 | <para> | ||
51 | Pseudo overrides system calls through the | ||
52 | <filename>LD_PRELOAD</filename> mechanism to give the | ||
53 | illusion of running as root. | ||
54 | To keep track of "fake" file ownership and permissions resulting from | ||
55 | operations that require root permissions, an sqlite3 | ||
56 | database is used. | ||
57 | This database is stored in | ||
58 | <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/pseudo/files.db</filename> | ||
59 | for individual recipes. | ||
60 | Storing the database in a file as opposed to in memory | ||
61 | gives persistence between tasks, and even between builds. | ||
62 | <note><title>Caution</title> | ||
63 | If you add your own task that manipulates the same files or | ||
64 | directories as a fakeroot task, then that task should also run | ||
65 | under fakeroot. | ||
66 | Otherwise, the task will not be able to run root-only operations, | ||
67 | and will not see the fake file ownership and permissions set by the | ||
68 | other task. | ||
69 | You should also add a dependency on | ||
70 | <filename>virtual/fakeroot-native:do_populate_sysroot</filename>, | ||
71 | giving the following: | ||
72 | <literallayout class='monospaced'> | ||
73 | fakeroot do_mytask () { | ||
74 | ... | ||
75 | } | ||
76 | do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" | ||
77 | </literallayout> | ||
78 | </note> | ||
79 | For more information, see the | ||
80 | <ulink url='&YOCTO_DOCS_BB_URL;#var-FAKEROOT'><filename>FAKEROOT*</filename></ulink> | ||
81 | variables in the BitBake User Manual. | ||
82 | You can also reference this | ||
83 | <ulink url='http://www.ibm.com/developerworks/opensource/library/os-aapseudo1/index.html'>Pseudo</ulink> | ||
84 | article. | ||
85 | </para> | ||
86 | </section> | ||
87 | |||
88 | <section id="wayland"> | 16 | <section id="wayland"> |
89 | <title>Wayland</title> | 17 | <title>Wayland</title> |
90 | 18 | ||
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 @@ | |||
1088 | I don't have much on this in the manual set. | 1088 | I don't have much on this in the manual set. |
1089 | Is there any more information we can leverage? | 1089 | Is there any more information we can leverage? |
1090 | For information on Fakeroot and Pseudo, see the | 1090 | For information on Fakeroot and Pseudo, see the |
1091 | "<ulink url='&YOCTO_DOCS_REF_URL;#fakeroot-and-pseudo'>Fakeroot and Pseudo</ulink>" | 1091 | "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#fakeroot-and-pseudo'>Fakeroot and Pseudo</ulink>" |
1092 | section in the Yocto Project Reference Manual. | 1092 | section in the Yocto Project Overview Manual. |
1093 | </para></listitem> | 1093 | </para></listitem> |
1094 | <listitem><para role='writernotes'> | 1094 | <listitem><para role='writernotes'> |
1095 | <emphasis>OPKG:</emphasis> | 1095 | <emphasis>OPKG:</emphasis> |