From 90d52bd51e0e34dc8ffd9c83c3d7fe9551dcce8f Mon Sep 17 00:00:00 2001
From: Scott Rifenbark <scott.m.rifenbark@intel.com>
Date: Mon, 7 Apr 2014 14:10:50 -0700
Subject: ref-manual: Added useradd-staticids class and edits to some
 variables.

Added the new useradd-staticids class to the reference section
for classes.

Updated the USERADD_UID_TABLES and USERADD_GID_TABLES variables
to tell how the system uses BBPATH in the default mode to
get UID and GID information from the files/passwd and files/group
files.

Added a note indicating that you can delete the TMPDIR directory
to fix things up if you configure useradd-staticids in a
configured system.

(From yocto-docs rev: a3f5ee3f5060369405d59a238fb02bddfeae5d6f)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 documentation/ref-manual/ref-classes.xml   | 54 ++++++++++++++++++++++++++++++
 documentation/ref-manual/ref-variables.xml | 22 +++++++++---
 2 files changed, 71 insertions(+), 5 deletions(-)

(limited to 'documentation/ref-manual')

diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index babe9bd2d6..df114f4eb2 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -3136,6 +3136,60 @@
     </para>
 </section>
 
+<section id='ref-classes-useradd-staticids'>
+    <title><filename>-useradd-staticids.bbclass</filename></title>
+
+    <para>
+        The <filename>useradd-staticids</filename> class supports the addition of
+        users or groups that have static user identification
+        (<filename>uid</filename>) and group identification
+        (<filename>gid</filename>) values.
+    </para>
+
+    <para>
+        The default behavior of the OpenEmbedded build system for assigning
+        <filename>uid</filename> and <filename>gid</filename> values when
+        packages add users and groups during package install time is to
+        look in
+        <link linkend='var-BBPATH'><filename>BBPATH</filename></link> for
+        <filename>files/passwd</filename> and <filename>files/group</filename>
+        files for the values.
+        This works fine for programs that do not care what the values of the
+        resulting users and groups become.
+        In these cases, the order of the installation determines the final
+        <filename>uid</filename> and <filename>gid</filename> values.
+    </para>
+
+    <para>
+        If non-deterministic
+        <filename>uid</filename> and <filename>gid</filename> values are a
+        problem, you can override the default, dynamic application of these
+        values by setting static values.
+        See the
+        <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
+        <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
+        <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>,
+        and
+        <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
+        variables for more information.
+        You can also see the
+        <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
+        class for additional information.
+    </para>
+
+    <note><title>Notes</title>
+        You do not use this class directly.
+        You either enable or disable the class by setting the
+        <filename>USERADDEXTENSION</filename> variable.
+        If you enable or disable the class in a configured system,
+        <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
+        might contain incorrect <filename>uid</filename> and
+        <filename>gid</filename> values.
+        Deleting the <filename>TMPDIR</filename> directory
+        will correct this condition.
+    </note>
+</section>
+
 <section id='ref-classes-utility-tasks'>
     <title><filename>utility-tasks.bbclass</filename></title>
 
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index d553ba8f71..6eae958e58 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -7853,8 +7853,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 </para>
 
                 <para>
-                    The default behavior for the build system is to dynamically
-                    apply <filename>gid</filename> values.
+                    The default behavior for the build system is to look in
+                    <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
+                    for a <filename>files/group</filename> file and then dynamically
+                    apply <filename>uid</filename> values.
                     However, you can override this behavior by using the
                     <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
                     variable.
@@ -7885,8 +7887,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 </para>
 
                 <para>
-                    The default behavior for the build system is to dynamically
-                    apply <filename>uid</filename> values.
+                    The default behavior for the build system is to look in
+                    <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
+                    for the <filename>files/passwd</filename> file and
+                    then dynamically apply <filename>uid</filename> values.
                     However, you can override this behavior by using the
                     <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
                     variable.
@@ -7965,7 +7969,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
-        <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENTION</glossterm>
+        <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm>
             <glossdef>
                 <para>
                     When set to "useradd-staticids", causes the
@@ -7980,6 +7984,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     <literallayout class='monospaced'>
      USERADDEXTENSION = "useradd-staticids"
                     </literallayout>
+                    <note>
+                        Setting this variable to use static
+                        <filename>uid</filename> and <filename>gid</filename>
+                        values causes the OpenEmbedded build system to employ
+                        the
+                        <link linkend='ref-classes-useradd-staticids'><filename>useradd-staticids</filename></link>
+                        class.
+                    </note>
                 </para>
 
                 <para>
-- 
cgit v1.2.3-54-g00ecf