* man/newusers.8.xml: Document the behavior of newusers for each

	field.
	* man/newusers.8.xml: Do not add the note on PAM on non-PAM
	enabled configurations.

diff --git a/ChangeLog b/ChangeLog
index d3996e9fe0836ec9573efc75c32721f7e547097b..9279037a479560cfbfe1832c74c011df269e4515 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2009-03-14  Nicolas François  <nicolas.francois@centraliens.net>
+
+       * man/newusers.8.xml: Document the behavior of newusers for each
+       field.
+       * man/newusers.8.xml: Do not add the note on PAM on non-PAM
+       enabled configurations.
+
 2009-03-13  Nicolas François  <nicolas.francois@centraliens.net>
 
        * src/newusers.c: Make sure the SHA related variables are not

diff --git a/man/newusers.8.xml b/man/newusers.8.xml
index 7ffdfd1f68f55e79581b5594b73377b3be827cf9..a043364dd76f81d5b17466a94077d097112c6a32 100644 (file)
--- a/man/newusers.8.xml
+++ b/man/newusers.8.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
    Copyright (c) 1991 - 1994, Julianne Frances Haugh
-   Copyright (c) 2007 - 2008, Nicolas François
+   Copyright (c) 2007 - 2009, Nicolas François
    All rights reserved.
   
    Redistribution and use in source and binary forms, with or without
@@ -73,10 +73,28 @@
       of existing users or to create new users. Each line is in the same format
       as the standard password file (see
       <citerefentry><refentrytitle>passwd</refentrytitle><manvolnum>5</manvolnum>
-      </citerefentry>) with the following exceptions:
+      </citerefentry>) with the exceptions explained below:
     </para>
+    <para>pw_name:pw_passwd:pw_uid:pw_gid:pw_gecos:pw_dir:pw_shell</para>
 
     <variablelist remap='IP'>
+      <varlistentry>
+       <term>
+         <emphasis remap='I'>pw_name</emphasis>
+       </term>
+       <listitem>
+         <para>
+           This is the name of the user.
+         </para>
+         <para>
+           It can be the name of a new user or the name of an existing
+           user (or an user created before by
+           <command>newusers</command>).  In case of an existing user,
+           the user's information will be changed, otherwise a new user
+           will be created.
+         </para>
+       </listitem>
+      </varlistentry>
       <varlistentry>
        <term>
          <emphasis remap='I'>pw_passwd</emphasis>
@@ -88,17 +106,73 @@
          </para>
        </listitem>
       </varlistentry>
+      <varlistentry>
+       <term>
+         <emphasis remap='I'>pw_uid</emphasis>
+       </term>
+       <listitem>
+         <para>
+           This field is used to define the UID of the user.
+         </para>
+         <para>
+           If the field is empty, an new (unused) UID will be defined
+           automatically by <command>newusers</command>.
+         </para>
+         <para>
+           If this field contains a number, this number will be used as
+           the UID.
+         </para>
+         <para>
+           If this field contains the name of an existing user (or the
+           name of an user created before by
+           <command>newusers</command>), the UID of the specified user
+           will be used.
+         </para>
+       </listitem>
+      </varlistentry>
       <varlistentry>
        <term>
          <emphasis remap='I'>pw_gid</emphasis>
        </term>
        <listitem>
          <para>
-           This field must contain the name (or number) of a group. The user
-           will be added as a member to this group. When a non-existent
-           group name or number is specified, a new group will be created.
-           In the case of a non-existent group number, both the name and the
-           number of the new group will be this number.
+           This field is used to define the primary group ID for the user.
+         </para>
+         <para>
+           If this field contains the name of an existing group (or a
+           group created before by <command>newusers</command>), the GID
+           of this group will be used as the primary group ID for the
+           user.
+         </para>
+         <para>
+           If this field is a number, this number will be used as the
+           primary group ID of the user.  If no groups exist with this
+           GID, a new group will be created with this GID, and the name
+           of the user.
+         </para>
+         <para>
+           If this field is empty, a new group will be created with the
+           name of the user and a GID will be automatically defined by
+           <command>newusers</command> to be used as the primary group ID
+           for the user and as the GID for the new group.
+         </para>
+         <para>
+           If this field contains the name of a group which does not
+           exist (and was not created earlier wbefore by
+           <command>newusers</command>), a new group will be created with
+           the specified name and a GID will be automatically defined by
+           <command>newusers</command> to be used as the primary group ID
+           for the user and Gs the ID for the new group.
+         </para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>
+         <emphasis remap='I'>pw_gecos</emphasis>
+       </term>
+       <listitem>
+         <para>
+           This field is copied in the GECOS field of the user.
          </para>
        </listitem>
       </varlistentry>
@@ -108,16 +182,36 @@
        </term>
        <listitem>
          <para>
-           This field will be checked for existence as a directory, and a
-           new directory with this name will be created if it does not
-           already exist. The ownership of the directory will be set to be
-           that of the user being created or updated.
+           This field is used to define the home directory of the user.
+         </para>
+         <para>
+           If this field does not specify an existing directory, the
+           specified directory is created, with ownership set to the
+           user being created or updated and its primary group.
+         </para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>
+         <emphasis remap='I'>pw_shell</emphasis>
+       </term>
+       <listitem>
+         <para>
+           This field defines the shell of the user.
+           No checks are performed on this field.
          </para>
        </listitem>
       </varlistentry>
     </variablelist>
 
-    <para> 
+    <para>
+      <command>newusers</command> first tries to create or change all the
+      specified users, and then write these changes to the user or group
+      databases. If an error occurs (except in the final writes to the
+      databases), no changes are committed to the databases.
+    </para>
+
+    <para>
       This command is intended to be used in a large system environment
       where many accounts are updated at a single time.
     </para>
@@ -191,7 +285,7 @@
       The input file must be protected since it contains unencrypted
       passwords.
     </para>
-    <para>
+    <para condition="pam">
       PAM is not used to update the passwords.
       Only <filename>/etc/passwd</filename> and
       <filename>/etc/shadow</filename> are updated, and the various checks