* Use <replaceable> for the values set by

  users. (was sometimes <emphasis remap='I'>)
* Use <option> vor the variable names. This
  makes the manpage much more readable.
* (ENCRYPT_METHOD, MD5_CRYPT_ENAB,
  SHA_CRYPT_MIN_ROUNDS, SHA_CRYPT_MAX_ROUNDS): Mention that command
  line option may supersede the system setting.
* Document the variables used by chpasswd
  and chgpasswd.

diff --git a/ChangeLog b/ChangeLog
index d3053fbbecb375c6d50a850f9e7469e4290aab17..8c5d018bf091f77f3fbb38bf95451748ce22f53a 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2007-11-22  Nicolas François  <nicolas.francois@centraliens.net>
+
+       * man/login.defs.5.xml: Use <replaceable> for the values set by
+       users. (was sometimes <emphasis remap='I'>)
+       * man/login.defs.5.xml: Use <option> vor the variable names. This
+       makes the manpage much more readable.
+       * man/login.defs.5.xml (ENCRYPT_METHOD, MD5_CRYPT_ENAB,
+       SHA_CRYPT_MIN_ROUNDS, SHA_CRYPT_MAX_ROUNDS): Mention that command
+       line option may supersede the system setting.
+       * man/login.defs.5.xml: Document the variables used by chpasswd
+       and chgpasswd.
+
 2007-11-22  Nicolas François  <nicolas.francois@centraliens.net>
 
        * lib/shadowmem.c, lib/groupmem.c, lib/pwmem.c:

diff --git a/man/login.defs.5.xml b/man/login.defs.5.xml
index a9804e77005b7eb0b76403332236048a4e63075a..15148b3c34bbc9b8326678086c10fc9264e2ebef 100644 (file)
--- a/man/login.defs.5.xml
+++ b/man/login.defs.5.xml
@@ -31,11 +31,15 @@
     <para>
       Parameter values may be of four types: strings, booleans, numbers, and
       long numbers. A string is comprised of any printable characters. A
-      boolean should be either the value "yes" or "no". An undefined boolean
-      parameter or one with a value other than these will be given a "no"
+      boolean should be either the value <replaceable>yes</replaceable> or
+      <replaceable>no</replaceable>. An undefined boolean
+      parameter or one with a value other than these will be given a
+      <replaceable>no</replaceable>
       value. Numbers (both regular and long) may be either decimal values,
-      octal values (precede the value with "0") or hexadecimal values
-      (precede the value with "0x"). The maximum value of the regular and
+      octal values (precede the value with <replaceable>0</replaceable>) or
+      hexadecimal values
+      (precede the value with <replaceable>0x</replaceable>).
+      The maximum value of the regular and
       long numeric parameters is machine-dependent.
     </para>
 
@@ -43,10 +47,10 @@
 
     <variablelist remap='IP'>
       <varlistentry>
-       <term>CHFN_AUTH (boolean)</term>
+       <term><option>CHFN_AUTH</option> (boolean)</term>
        <listitem>
          <para>
-           If <emphasis remap='I'>yes</emphasis>, the
+           If <replaceable>yes</replaceable>, the
            <command>chfn</command> and <command>chsh</command> programs
            will require authentication before making any changes, unless
            run by the superuser.
@@ -54,45 +58,55 @@
        </listitem>
       </varlistentry>
       <varlistentry>
-       <term>CHFN_RESTRICT (string)</term>
+       <term><option>CHFN_RESTRICT</option> (string)</term>
        <listitem>
          <para>
            This parameter specifies which values in the <emphasis
            remap='I'>gecos</emphasis> field of the
            <filename>/etc/passwd</filename> file may be changed by regular
            users using the <command>chfn</command> program. It can be any
-           combination of letters <emphasis remap='I'>f</emphasis>
-           ,<emphasis remap='I'>r</emphasis>, <emphasis remap='I'>w</emphasis>,
-           <emphasis remap='I'>h</emphasis>, for Full name, Room number,
+           combination of letters <replaceable>f</replaceable>,
+           <replaceable>r</replaceable>, <replaceable>w</replaceable>,
+           <replaceable>h</replaceable>, for Full name, Room number,
            Work phone, and Home phone, respectively. For backward
-           compatibility, "yes" is equivalent to "rwh" and "no" is
-           equivalent to "frwh". If not specified, only the superuser can
+           compatibility, <replaceable>yes</replaceable> is equivalent to
+           <replaceable>rwh</replaceable> and
+           <replaceable>no</replaceable> is
+           equivalent to <replaceable>frwh</replaceable>. If not specified,
+           only the superuser can
            make any changes. The most restrictive setting is better
-           achieved by not installing <filename>chfn</filename> SUID.
+           achieved by not installing <command>chfn</command> SUID.
          </para>
        </listitem>
       </varlistentry>
       <varlistentry>
-       <term>ENCRYPT_METHOD (string)</term>
+       <term><option>ENCRYPT_METHOD</option> (string)</term>
        <listitem>
          <para>
-           If set to MD5, the MD5-based algorithm will be used for
-           encrypting passwords.
+           This defines the system default encryption algorithm for
+           encrypting passwords (if no algorithm are specified on the
+           command line).
          </para>
          <para>
-           If set to SHA256, the SHA256-based algorithm will be used for
-           encrypting passwords.
+           It can take one of these values:
+           <itemizedlist>
+             <listitem>
+               <para><replaceable>DES</replaceable> (default)</para>
+             </listitem>
+             <listitem>
+               <para><replaceable>MD5</replaceable></para>
+             </listitem>
+             <listitem>
+               <para><replaceable>SHA256</replaceable></para>
+             </listitem>
+             <listitem>
+               <para><replaceable>SHA512</replaceable></para>
+             </listitem>
+           </itemizedlist>
          </para>
          <para>
-           If set to SHA512, the SHA512-based algorithm will be used for
-           encrypting passwords.
-         </para>
-         <para>
-           If set to DES, the DES-based algorithm will be used for
-           encrypting passwords. It is the default algorithm.
-         </para>
-         <para>
-           Note: this parameter overrides the MD5_CRYPT_ENAB option.
+           Note: this parameter overrides the
+           <option>MD5_CRYPT_ENAB</option> variable.
          </para>
          <para>
            Note: if you use PAM, it is recommended to set this variable
@@ -101,8 +115,8 @@
        </listitem>
       </varlistentry>
       <varlistentry>
-       <term>GID_MAX (number)</term>
-       <term>GID_MIN (number)</term>
+       <term><option>GID_MAX</option> (number)</term>
+       <term><option>GID_MIN</option> (number)</term>
        <listitem>
          <para>
            Range of group IDs to choose from for the
@@ -112,7 +126,7 @@
        </listitem>
       </varlistentry>
       <varlistentry>
-       <term>MAIL_DIR (string)</term>
+       <term><option>MAIL_DIR</option> (string)</term>
        <listitem>
          <para>
            The mail spool directory. This is needed to manipulate the
@@ -122,11 +136,11 @@
        </listitem>
       </varlistentry>
       <varlistentry>
-       <term>MAX_MEMBERS_PER_GROUP (number)</term>
+       <term><option>MAX_MEMBERS_PER_GROUP</option> (number)</term>
        <listitem>
          <para>
            Maximum members per group entry. When the maximum is reached,
-           a new group entry (line) is started is
+           a new group entry (line) is started in
            <filename>/etc/group</filename> (with the same name, same
            password, and same GID).
          </para>
@@ -146,25 +160,34 @@
          </para>
          <para>
            Note: split groups may not be supported by all tools (even in
-           the Shadow toolsuite. Yous hould not use this variable unless
+           the Shadow toolsuite. You should not use this variable unless
            you really need it.
          </para>
        </listitem>
       </varlistentry>
       <varlistentry>
-       <term>MD5_CRYPT_ENAB (boolean)</term>
+       <term><option>MD5_CRYPT_ENAB</option> (boolean)</term>
        <listitem>
          <para>
            Indicate if passwords must be encrypted using the MD5-based
-           algorithm. If set to "yes", new passwords will be encrypted
+           algorithm. If set to <replaceable>yes</replaceable>, new
+           passwords will be encrypted
            using the MD5-based algorithm compatible with the one used by
            recent releases of FreeBSD. It supports passwords of
-           unlimited length and longer salt strings. Set to "no" if you
+           unlimited length and longer salt strings. Set to
+           <replaceable>no</replaceable> if you
            need to copy encrypted passwords to other systems which don't
-           understand the new algorithm. Default is "no".
+           understand the new algorithm. Default is
+           <replaceable>no</replaceable>.
+         </para>
+         <para>
+           This variable is superceded by the
+           <option>ENCRYPT_METHOD</option> variable or by any command
+           line option used to configure the encryption algorithm.
          </para>
          <para>
-           This variable is deprecated. You should use ENCRYPT_METHOD.
+          This variable is deprecated. You should use
+          <option>ENCRYPT_METHOD</option>.
          </para>
          <para>
            Note: if you use PAM, it is recommended to set this variable
@@ -173,7 +196,7 @@
        </listitem>
       </varlistentry>
       <varlistentry>
-       <term>PASS_MAX_DAYS (number)</term>
+       <term><option>PASS_MAX_DAYS</option> (number)</term>
        <listitem>
          <para>
            The maximum number of days a password may be used. If the
@@ -184,7 +207,7 @@
        </listitem>
       </varlistentry>
       <varlistentry>
-       <term>PASS_MIN_DAYS (number)</term>
+       <term><option>PASS_MIN_DAYS</option> (number)</term>
        <listitem>
          <para>
            The minimum number of days allowed between password changes. 
@@ -195,7 +218,7 @@
        </listitem>
       </varlistentry>
       <varlistentry>
-       <term>PASS_WARN_AGE (number)</term>
+       <term><option>PASS_WARN_AGE</option> (number)</term>
        <listitem>
          <para>
            The number of days warning given before a password expires. A
@@ -208,18 +231,22 @@
     </variablelist>
 
     <para> 
-      PASS_MAX_DAYS, PASS_MIN_DAYS and PASS_WARN_AGE are only used at the
+      <option>PASS_MAX_DAYS</option>, <option>PASS_MIN_DAYS</option> and
+      <option>PASS_WARN_AGE</option> are only used at the
       time of account creation. Any changes to these settings won't affect
       existing accounts.
     </para>
     <variablelist remap='IP'>
       <varlistentry>
-       <term>SHA_CRYPT_MIN_ROUNDS (number)</term>
-       <term>SHA_CRYPT_MAX_ROUNDS (number)</term>
+       <term><option>SHA_CRYPT_MIN_ROUNDS</option> (number)</term>
+       <term><option>SHA_CRYPT_MAX_ROUNDS</option> (number)</term>
        <listitem>
          <para>
-           When ENCRYPT_METHOD is set to SHA256 or SHA512, this defines
-           the number of SHA rounds used by the encryption algorithm.
+           When <option>ENCRYPT_METHOD</option> is set to
+           <replaceable>SHA256</replaceable> or
+           <replaceable>SHA512</replaceable>, this defines the number of
+           SHA rounds used by the encryption algorithm by default (when
+           the number of rounds is not specified on the command line).
          </para>
          <para>
            With a lot of rounds, it is more difficult to brute forcing
@@ -227,24 +254,27 @@
            needed to authenticate users.
          </para>
          <para>
-           If not specified, the libc will choose the default number of rounds
-           (5000).
+           If not specified, the libc will choose the default number of
+           rounds (5000).
          </para>
          <para>
            The values must be inside the 1000-999999999 range.
          </para>
          <para>
-           If only one of the MIN or MAX values is set, then this value will be
-           used.
+           If only one of the <option>SHA_CRYPT_MIN_ROUNDS</option> or
+           <option>SHA_CRYPT_MAX_ROUNDS</option> values is set, then this
+           value will be used.
          </para>
          <para>
-           If MIN &gt; MAX, the highest value will be used.
+           If <option>SHA_CRYPT_MIN_ROUNDS</option> &gt;
+           <option>SHA_CRYPT_MAX_ROUNDS</option>, the highest value will
+           be used.
          </para>
        </listitem>
       </varlistentry>
       <varlistentry>
-       <term>UID_MAX (number)</term>
-       <term>UID_MIN (number)</term>
+       <term><option>UID_MAX</option> (number)</term>
+       <term><option>UID_MIN</option> (number)</term>
        <listitem>
          <para>
            Range of user IDs to choose from for the
@@ -253,7 +283,7 @@
        </listitem>
       </varlistentry>
       <varlistentry>
-       <term>UMASK (number)</term>
+       <term><option>UMASK</option> (number)</term>
        <listitem>
          <para>
            The permission mask is initialized to this value. If not
@@ -262,7 +292,7 @@
        </listitem>
       </varlistentry>
       <varlistentry>
-       <term>USERDEL_CMD (string)</term>
+       <term><option>USERDEL_CMD</option> (string)</term>
        <listitem>
          <para>
            If defined, this command is run when removing a user. It should
@@ -288,6 +318,24 @@
          <para>CHFN_AUTH CHFN_RESTRICT</para>
        </listitem>
       </varlistentry>
+      <varlistentry>
+       <term>chgpasswd</term>
+       <listitem>
+         <para>
+           MD5_CRYPT_ENAB ENCRYPT_METHOD SHA_CRYPT_MIN_ROUNDS
+           SHA_CRYPT_MAX_ROUNDS MAX_MEMBERS_PER_GROUP
+         </para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>chpasswd</term>
+       <listitem>
+         <para>
+           MD5_CRYPT_ENAB ENCRYPT_METHOD SHA_CRYPT_MIN_ROUNDS
+           SHA_CRYPT_MAX_ROUNDS
+         </para>
+       </listitem>
+      </varlistentry>
       <varlistentry>
        <term>chsh</term>
        <listitem>
@@ -303,8 +351,8 @@
       <varlistentry>
        <term>newusers</term>
        <listitem>
-         <para>PASS_MAX_DAYS PASS_MIN_DAYS PASS_WARN_AGE
-           UMASK
+         <para>
+           PASS_MAX_DAYS PASS_MIN_DAYS PASS_WARN_AGE UMASK
          </para>
        </listitem>
       </varlistentry>