usermanual: Add details on fakeroot to the reference section. Update

the carious places in the image_ipkg and rootfs_ipkg that talk about
fakeroot to refer to the fakeroot section.

3 files changed, 224 insertions, 37 deletions

diff --git a/usermanual/reference/class_image_ipkg.xml b/usermanual/reference/class_image_ipkg.xml
index 814068c711..31eb2e6f29 100644
--- a/usermanual/reference/class_image_ipkg.xml
+++ b/usermanual/reference/class_image_ipkg.xml
@@ -137,7 +137,9 @@
       <term>IMAGE_PREPROCESS_COMMAND</term>
 
       <listitem>
-        <para>Additional commands to run prior to processing the image.</para>
+        <para>Additional commands to run prior to processing the image. Note
+        that these command runs within the same <xref linkend="fakeroot" />
+        instance as the rest of this class.</para>
 
         <para>Default: <command>""</command></para>
       </listitem>
@@ -147,7 +149,9 @@
       <term>IMAGE_POSTPROCESS_COMMAND</term>
 
       <listitem>
-        <para>Additional commands to run after processing the image.</para>
+        <para>Additional commands to run after processing the image. Note that
+        these command runs within the same <xref linkend="fakeroot" />
+        instance as the rest of this class.</para>
 
         <para>Default: <command>""</command></para>
       </listitem>
@@ -184,19 +188,16 @@
   <section>
     <title>Special node handling (fakeroot)</title>
 
-    <para>Special nodes, such as /dev nodes, and files with special
-    permissions, such as suid files, are handled via the fakeroot system. This
-    means that when you view the contents of the root filesystem these device
-    appear to be created incorrectly:</para>
-
-    <para>While these devices do not appear correctly on disk, fakeroot keeps
-    track of what they should be and when generating images it will provide
-    the proper files to the commands (such as tar) which are processing the
-    root filesystem. Note that for this to work all of the commands related to
-    generating the image must be run under fakeroot. This is the remove for
-    the IMAGE_PREPROCESS_COMMAND and IMAGE_POSTPROCESS_COMMAND variables -
-    these variables are processed while still under the fakeroot
-    process.</para>
+    <para>Special nodes, such as <command>/dev</command> nodes, and files with
+    special permissions, such as suid files, are handled via the <xref
+    linkend="fakeroot" /> system. This means that when you view the contents
+    of the root filesystem these device appear to be created
+    incorrectly:</para>
+
+    <para>The <command>IMAGE_PREPROCESS_COMMAND</command> and
+    <command>IMAGE_POSTPROCESS_COMMAND</command> variables will be processed
+    within the same <xref linkend="fakeroot" /> instance as the rest of the
+    rest of this class.</para>
   </section>
 
   <section>
@@ -204,11 +205,11 @@
 
     <para>There are two variables that can be defined for creating device
     nodes. The newer version supports multiple device node tables and searches
-    for the specified files along ${BBPATH} so that relative file names may be
-    used.</para>
+    for the specified files along <command>${BBPATH}</command> so that
+    relative file names may be used.</para>
 
-    <para>The following example from machine/titan.conf shows the use of
-    multiple device tables:</para>
+    <para>The following example from <command>machine/titan.conf</command>
+    shows the use of multiple device tables:</para>
 
     <para><screen># Add the SCI devices to minimal /dev
 IMAGE_DEVICE_TABLES = "files/device_table-minimal.txt files/device_table_add-sci.txt device_table_add-sm.txt"
@@ -230,10 +231,11 @@ IMAGE_DEVICE_TABLES = "files/device_table-minimal.txt files/device_table_add-sci
         <term>files/device_table_add-sci.txt</term>
 
         <listitem>
-          <para>This contains details for creating the /dev/SC{0,1,2} nodes
-          which are required for the SH processors on board SCI and SCIF
-          serial ports. On the titan the serial console is provided via one of
-          these ports and so we require the device node to be present.</para>
+          <para>This contains details for creating the
+          <command>/dev/SC{0,1,2}</command> nodes which are required for the
+          SH processors on board SCI and SCIF serial ports. On the titan the
+          serial console is provided via one of these ports and so we require
+          the device node to be present.</para>
         </listitem>
       </varlistentry>
 
@@ -241,10 +243,10 @@ IMAGE_DEVICE_TABLES = "files/device_table-minimal.txt files/device_table_add-sci
         <term>device_table_add-sm.txt</term>
 
         <listitem>
-          <para>This contains details fro creating the /dev/sm0 and
-          /dev/sm0p{0,1,2} devices nodes for the block driver and associated
-          partitions that is used to managed the flash on the titan
-          board.</para>
+          <para>This contains details fro creating the
+          <command>/dev/sm0</command> and <command>/dev/sm0p{0,1,2}</command>
+          devices nodes for the block driver and associated partitions that is
+          used to managed the flash on the titan board.</para>
         </listitem>
       </varlistentry>
     </variablelist>
diff --git a/usermanual/reference/class_rootfs_ipkg.xml b/usermanual/reference/class_rootfs_ipkg.xml
index 095c3278be..40a17acfe2 100644
--- a/usermanual/reference/class_rootfs_ipkg.xml
+++ b/usermanual/reference/class_rootfs_ipkg.xml
@@ -203,14 +203,14 @@
     </varlistentry>
   </variablelist>
 
-  <para>Note that the entire process is run under the control of fakeroot, so
-  any permissions, special devices files etc will be remember by fakeroot by
-  lost once the class has completed. This is why the
-  <command>ROOTFS_POSTPROCESS_COMMAND</command> is useful - it performs it's
-  actions while under the control of fakeroot. The class also provides a
-  function real_do_rootfs which is executed without fakeroot - this is used
-  from other classes, such as <xref linkend="image_ipkg_class" />, to perform
-  the functionality of this class under the control of it's own fakeroot
-  process so that it can perform additional actions under the control of
-  fakeroot in addition to that performed by the rootfs_ipkg class.</para>
+  <para>Note that the entire process is run under the control of <xref
+  linkend="fakeroot" /> in order to handle device files, uid and gid's. The
+  <command>ROOTFS_POSTPROCESS_COMMAND</command> is useful due to the fact that
+  it runs within he same <xref linkend="fakeroot" /> instance as the rest of
+  this class.</para>
+
+  <para>The class also provides a function <command>real_do_rootfs</command>
+  which is executed without <xref linkend="fakeroot" /> and therefore can be
+  used from other classes, such as <xref linkend="image_ipkg_class" />, that
+  are already running under the control of <xref linkend="fakeroot" />.</para>
 </section>
\ No newline at end of file
diff --git a/usermanual/reference/fakeroot.xml b/usermanual/reference/fakeroot.xml
new file mode 100644
index 0000000000..4b5e2c6c31
--- /dev/null
+++ b/usermanual/reference/fakeroot.xml
@@ -0,0 +1,185 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="fakeroot" xreflabel="fakeroot">
+  <title>fakeroot (device node handling)</title>
+
+  <para>The fakeroot program is designed to allow non-root users to perform
+  actions that normally require root as part of the package generation
+  process. It is used by <xref linkend="rootfs_ipkg_class" /> the for root
+  filesystem creation and by <xref linkend="image_ipkg_class" /> the for image
+  creation. Some recipies also use fakeroot to assist with parts of the
+  package installation (usually) or building that requires root
+  priviliges.</para>
+
+  <para>In particular fakeroot deals with:</para>
+
+  <itemizedlist>
+    <listitem>
+      <para>Device nodes; and</para>
+    </listitem>
+
+    <listitem>
+      <para>Ownership and group (uid &amp; gid) management.</para>
+    </listitem>
+  </itemizedlist>
+
+  <section>
+    <title>How fakeroot works</title>
+
+    <para>First of all we'll look at an example of how the fakeroot process
+    works when used manually.</para>
+
+    <para>If we attempt to create a device node as a normal (non-root) user
+    the command will fail, telling is that we do not have permission to create
+    device nodes:<screen>~%&gt; mknod hdc b 22 0
+mknod: `hdc': Operation not permitted</screen>Yet the <xref
+    linkend="image_ipkg_class" /> is able to create device nodes and include
+    them in the final images, qll without the need to have root
+    priviliges.</para>
+
+    <para>Let's try and create that node again, this time we'll run the
+    commands from within the fakeroot process:<screen>~%&gt; ./tmp/staging/x86_64-linux/bin/fakeroot
+~#&gt; mknod hdc b 22 0
+~#&gt; ls -l hdc
+brw-------  1 root root 22, 0 Aug 18 13:20 hdc
+~#&gt;</screen>So it looks like we have succesfully managed to create a device
+    node, even though we did not have to give a password for the root user. In
+    reality this device node still doesn't exist, it just looks like it
+    exists. Fakeroot is lying to the shell process and telling it that
+    <emphasis>"yes, this file exists and these are it's
+    properties"</emphasis>. We'll talk more about how fakeroot actually works
+    in a minute.</para>
+
+    <para>In this case <command>hdc</command> is the cd-rom drive, so let's
+    try and actually mount the cd-rom:<screen>~#&gt; mkdir disk
+~#&gt; mount hdc disk
+ERROR: ld.so: object 'libfakeroot.so.0' from LD_PRELOAD cannot be preloaded: ignored.
+mount: only root can do that
+~#&gt;</screen>So even though it appears we have root permissions, and that we
+    created a device node, you see that the system gives an error about
+    libfakeroot and about not being able to run mount because we are not
+    root.</para>
+
+    <para>If we exit the fakeroot process and then look at the device node we
+    see this:<screen>~#&gt; exit
+~%&gt; ls -l hdc
+brw-------  1 user user 22, 0 Aug 18 13:20 hdc
+~#&gt;</screen></para>
+
+    <para>Note that it isn't a device node at all, just an empty file owned by
+    the current user!</para>
+
+    <para>So what exactly is fakeroot doing? It's using
+    <command>LD_PRELOAD</command> to load a shared libary into program which
+    replaces calls into libc, such as open and stat, and then returns
+    information to make it look like certain commands without actually
+    performing them. So when creating a device node fakeroot will:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>Intercept the mknod system call and instead of creating a device
+        node it'll just created an empty file, owned by the user who run
+        fakeroot;</para>
+      </listitem>
+
+      <listitem>
+        <para>It rembers the fact that mknod was called by root and the
+        properties of the device node;</para>
+      </listitem>
+
+      <listitem>
+        <para>When a program, such as ls, calls stat on the file fakeroot
+        remebers that it was device node, owned by root, and modifies that
+        stat information to return this to ls. So ls sees a device node even
+        though one doesn't exist.</para>
+      </listitem>
+    </orderedlist>
+
+    <para>When we tried to run mount we recieved the error <command>"ERROR:
+    ld.so: object 'libfakeroot.so.0' from LD_PRELOAD cannot be preloaded:
+    ignored."</command>. This is due to the fact that mount is an suid root
+    binary, and for security reasons <command>LD_PRELOAD</command> is disabled
+    on suid binaries.</para>
+
+    <para>There are some very important points to remember when dealing with
+    fakeroot:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>All information regarding devices nodes, uid and gids will be
+        lost when fakeroot exists;</para>
+      </listitem>
+
+      <listitem>
+        <para>None of the device nodes, uid or gid's will appear on disk,
+        however if you for example tar up a directory from within fakeroot all
+        of these device, uid's and gid's will appear in the tar
+        archive;</para>
+      </listitem>
+
+      <listitem>
+        <para>Any suid binaries will not interact with fakeroot;</para>
+      </listitem>
+
+      <listitem>
+        <para>Any static binaries will not interact with fakeroot;</para>
+      </listitem>
+    </orderedlist>
+
+  </section>
+
+  <section>
+    <title>Root filesystem, images and fakeroot</title>
+
+    <para>Many people have been been confused by the generated root filesystem
+    not containing and valid device nodes. But this is the expected
+    behaviour.</para>
+
+    <para>When you look at a generated root filesystem you'll notice that the
+    device nodes all appear to be incorrectly created:<screen>~%&gt; ls -l tmp/rootfs/dev | grep ttySC
+-rw-r--r--  1 root root 0 Aug 16 13:07 ttySC0
+-rw-r--r--  1 root root 0 Aug 16 13:07 ttySC1
+-rw-r--r--  1 root root 0 Aug 16 13:07 ttySC2
+~%&gt;</screen>These are empty files and not device nodes at all.</para>
+
+    <para>If we look in the image files generated from that root filesystem
+    everthing is actually ok:<screen>~%&gt; tar -ztvf tmp/deploy/images/titan-titan-20060816030639.rootfs.tar.gz | grep " ./dev/ttySC"
+crw-r----- root/root     204,8 2006-08-16 13:07:12 ./dev/ttySC0
+crw-r----- root/root     204,9 2006-08-16 13:07:12 ./dev/ttySC1
+crw-r----- root/root    204,10 2006-08-16 13:07:12 ./dev/ttySC2
+~%&gt;</screen>The images are created from within the same fakeroot process as
+    the creation of the root filesystem and therefore it correctly picks up
+    all of the special files and permissions from fakeroot.</para>
+
+    <para><emphasis role="bold">NOTE: This means that you cannot use the root
+    filesystem in tmp/rootfs directly on your target device. You need to use
+    the .tar.gz image and uncompress it as root in order to generate a root
+    filesystem which is suitable for use directly on the target (or as an NFS
+    root).</emphasis></para>
+  </section>
+
+  <section>
+    <title>Recipes and fakeroot</title>
+
+    <para>Some applications require that you have root permissions to run
+    their installation routine, and this is another area where fakeroot can
+    help. In a recipe a standard task, such as <emphasis>do_install</emphasis>
+    for example:<screen>do_install() {
+    install -d ${D}${bindir} ${D}${sbindir} ${D}${mandir}/man8 \
+               ${D}${sysconfdir}/default \
+               ${D}${sysconfdir}/init.d \
+               ${D}${datadir}/arpwatch
+
+    oe_runmake install DESTDIR=${D}
+    oe_runmake install-man DESTDIR=${D}
+    ...</screen>can be modified to run within a fakeroot environment by
+    prefings the task with fakeroot:<screen><emphasis role="bold">fakeroot</emphasis> do_install() {
+    install -d ${D}${bindir} ${D}${sbindir} ${D}${mandir}/man8 \
+               ${D}${sysconfdir}/default \
+               ${D}${sysconfdir}/init.d \
+               ${D}${datadir}/arpwatch
+
+    oe_runmake install DESTDIR=${D}
+    oe_runmake install-man DESTDIR=${D}
+    ...</screen></para>
+  </section>
+</section>
\ No newline at end of file