ref-manual: New variables to support static uid and gid values.

Added variable descriptions for the following variables:

* USERADDEXTENTIONS
* USERADD_UID_TABLES
* USERADD_GID_TABLES
* USERADD_ERROR_DYNAMIC.

(From yocto-docs rev: 988c21db5ca2bc5a6884acc2320e0143e3a7cf14)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 135 insertions, 0 deletions

diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 210d15099f..58b508e516 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -7806,6 +7806,107 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm>
+            <glossdef>
+                <para>
+                    Forces the OpenEmbedded build system to produce an error
+                    if the user identification (<filename>uid</filename>) and
+                    group identification (<filename>gid</filename>) values
+                    are not defined in <filename>files/passwd</filename>
+                    and <filename>files/group</filename> files.
+                </para>
+
+                <para>
+                    The default behavior for the build system is to dynamically
+                    apply <filename>uid</filename> and
+                    <filename>gid</filename> values.
+                    Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename>
+                    variable is by default not set.
+                    If you plan on using statically assigned
+                    <filename>gid</filename> and <filename>uid</filename>
+                    values, you should set
+                    the <filename>USERADD_ERROR_DYNAMIC</filename> variable in
+                    your <filename>local.conf</filename> file as
+                    follows:
+                    <literallayout class='monospaced'>
+     USERADD_ERROR_DYNAMIC = "1"
+                    </literallayout>
+                    Overriding the default behavior implies you are going to
+                    also take steps to set static <filename>uid</filename> and
+                    <filename>gid</filename> values through use of the
+                    <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
+                    <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
+                    and
+                    <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
+                    variables.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm>
+            <glossdef>
+                <para>
+                    Specifies a password file to use for obtaining static
+                    group identification (<filename>gid</filename>) values
+                    when the OpenEmbedded build system adds a group to the
+                    system during package installation.
+                </para>
+
+                <para>
+                    The default behavior for the build system is to dynamically
+                    apply <filename>gid</filename> values.
+                    However, you can override this behavior by using the
+                    <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
+                    variable.
+                    When you do use static values, you must also set the
+                    <filename>USERADD_GID_TABLES</filename> variable in your
+                    <filename>local.conf</filename> file as follows:
+                    <literallayout class='monospaced'>
+     USERADD_GID_TABLES = "files/group"
+                    </literallayout>
+                </para>
+
+                <note>
+                    When using static information for user adds, you must
+                    also use the
+                    <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
+                    variable.
+                </note>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm>
+            <glossdef>
+                <para>
+                    Specifies a password file to use for obtaining static
+                    user identification (<filename>uid</filename>) values
+                    when the OpenEmbedded build system adds a user to the
+                    system during package installation.
+                </para>
+
+                <para>
+                    The default behavior for the build system is to dynamically
+                    apply <filename>uid</filename> values.
+                    However, you can override this behavior by using the
+                    <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
+                    variable.
+                    When you do use static values, you must also set the
+                    <filename>USERADD_UID_TABLES</filename> variable in your
+                    <filename>local.conf</filename> file as follows:
+                    <literallayout class='monospaced'>
+     USERADD_UID_TABLES = "files/passwd"
+                    </literallayout>
+                </para>
+
+                <note>
+                    When using static information for group adds, you must
+                    also use the
+                    <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
+                    variable.
+                </note>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm>
             <glossdef>
                 <para>
@@ -7863,6 +7964,40 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 </para>
             </glossdef>
         </glossentry>
+
+        <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENTION</glossterm>
+            <glossdef>
+                <para>
+                    When set to "useradd-staticids", causes the
+                    OpenEmbedded build system to base all user and group
+                    additions on a static
+                    <filename>passwd</filename> and
+                    <filename>group</filename> files.
+                    To use static user identification (<filename>uid</filename>)
+                    and group identification (<filename>gid</filename>)
+                    values, set the variable
+                    as follows in your <filename>local.conf</filename> file:
+                    <literallayout class='monospaced'>
+     USERADDEXTENSION = "useradd-staticids"
+                    </literallayout>
+                </para>
+
+                <para>
+                    If you use static <filename>uid</filename> and
+                    <filename>gid</filename> information, you must also
+                    specify the <filename>files/passwd</filename> and
+                    <filename>files/group</filename> files by setting the
+                    <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
+                    and
+                    <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
+                    variables.
+                    Additionally, you should also set the
+                    <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
+                    variable.
+                </para>
+            </glossdef>
+        </glossentry>
+
     </glossdiv>
 
 <!--            <glossdiv id='var-glossary-v'><title>V</title>-->