From d316ba1b87b93abb4d8b3db468ba0868debf3414 Mon Sep 17 00:00:00 2001
From: nekral-guest <nekral-guest@5a98b0ae-9ef6-0310-add3-de5d479b70d7>
Date: Fri, 23 Nov 2007 19:55:47 +0000
Subject: [PATCH] * 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.

---
 ChangeLog            |  12 ++++
 man/login.defs.5.xml | 162 ++++++++++++++++++++++++++++---------------
 2 files changed, 117 insertions(+), 57 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index d3053fbb..8c5d018b 100644
--- 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 a9804e77..15148b3c 100644
--- 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 deprecated. You should use ENCRYPT_METHOD.
+	    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
+	   <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>