shadow/man/chpasswd.8.xml

<?xml version="1.0" encoding="UTF-8"?>
<refentry id='chpasswd.8'>
  <!-- $Id$ -->
  <refmeta>
    <refentrytitle>chpasswd</refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo class="sectdesc">System Management Commands</refmiscinfo>
  </refmeta>
  <refnamediv id='name'>
    <refname>chpasswd</refname>
    <refpurpose>update passwords in batch mode</refpurpose>
  </refnamediv>

  <refsynopsisdiv id='synopsis'>
    <cmdsynopsis>
      <command>chpasswd</command>
      <arg choice='opt'>
	<replaceable>options</replaceable>
      </arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1 id='description'>
    <title>DESCRIPTION</title>
    <para>
      The <command>chpasswd</command> command reads a list of user name and
      password pairs from standard input and uses this information to update
      a group of existing users. Each line is of the format:
    </para>
    <para>
      <emphasis remap='I'>user_name</emphasis>:<emphasis
      remap='I'>password</emphasis>
    </para>
    <para>
      By default the supplied password must be in clear-text, and is
      encrypted by <command>chpasswd</command>.
      Also the password age will be updated, if present.
    </para>
    <para>
      The default encryption algorithm can be defined for the system with
      the ENCRYPT_METHOD variable of <filename>/etc/login.defs</filename>,
      and can be overwiten with the <option>-e</option>,
      <option>-m</option>, or <option>-c</option> options.
    </para>
    <para>
      This command is intended to be used in a large system environment
      where many accounts are created at a single time.
    </para>
  </refsect1>

  <refsect1 id='options'>
    <title>OPTIONS</title>
    <para>
      The options which apply to the <command>chpasswd</command> command
      are:
    </para>
    <variablelist remap='IP'>
      <varlistentry>
	<term><option>-c</option>, <option>--crypt-method</option></term>
	<listitem>
	  <para>Use the specified method to encrypt the passwords.</para>
	  <para>
	    The available methods are DES, MD5, and SHA256 or SHA512
	    if compiled with the ENCRYPTMETHOD_SELECT flag.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-e</option>, <option>--encrypted</option></term>
	<listitem>
	  <para>Supplied passwords are in encrypted form.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-h</option>, <option>--help</option></term>
	<listitem>
	  <para>Display help message and exit.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-m</option>, <option>--md5</option></term>
	<listitem>
	  <para>
	    Use MD5 encryption instead of DES when the supplied passwords are
	    not encrypted.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-s</option>, <option>--sha-rounds</option></term>
	<listitem>
	  <para>
	    Use the specified number of rounds to encrypt the passwords.
	  </para>
	  <para>
	    The value 0 means that the system will choose the default
	    number of rounds for the crypt method (5000).
	  </para>
	  <para>
	    A minimal value of 1000 and a maximal value of 999,999,999
	    will be enforced.
	  </para>
	  <para>
	    You can only use this option with the SHA256 or SHA512
	    crypt method.
	  </para>
	  <para>
	    By default, the number of rounds is defined by the
	    SHA_CRYPT_MIN_ROUNDS and SHA_CRYPT_MAX_ROUNDS variables in
	    <filename>/etc/login.defs</filename>.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id='caveats'>
    <title>CAVEATS</title>
    <para>
      Remember to set permissions or umask to prevent readability of
      unencrypted files by other users.
    </para>
    <para>
      PAM is not used to update the passwords.
      Thus, only <filename>/etc/passwd</filename> and
      <filename>/etc/shadow</filename> are updated, and the various checks
      or options provided by PAM modules are not used.
    </para>
  </refsect1>

  <refsect1 id='configuration'>
    <title>CONFIGURATION</title>
    <para>
      The following configuration variables in
      <filename>/etc/login.defs</filename> change the behavior of this
      tool:
    </para>
    <!--********************************************************************
      **                                                                  **
      **             Definitions copied from login.def.5.xml              **
      **                                                                  **
      ********************************************************************-->
    <variablelist>
      <varlistentry>
	<term><option>MD5_CRYPT_ENAB</option> (boolean)</term>
	<listitem>
	  <para>
	    Indicate if passwords must be encrypted using the MD5-based
	    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
	    <replaceable>no</replaceable> if you
	    need to copy encrypted passwords to other systems which don't
	    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.
	  </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
	    consistently with the PAM modules configuration.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>ENCRYPT_METHOD</option> (string)</term>
	<listitem>
	  <para>
	    This defines the system default encryption algorithm for
	    encrypting passwords (if no algorithm are specified on the
	    command line).
	  </para>
	  <para>
	    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>
	    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
	    consistently with the PAM modules configuration.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>SHA_CRYPT_MIN_ROUNDS</option> (number)</term>
	<term><option>SHA_CRYPT_MAX_ROUNDS</option> (number)</term>
	<listitem>
	  <para>
	    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
	    the password. But note also that more CPU resources will be
	    needed to authenticate users.
	  </para>
	  <para>
	    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 <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 <option>SHA_CRYPT_MIN_ROUNDS</option> &gt;
	    <option>SHA_CRYPT_MAX_ROUNDS</option>, the highest value will
	    be used.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id='files'>
    <title>FILES</title>
    <variablelist>
      <varlistentry>
	<term><filename>/etc/passwd</filename></term>
	<listitem>
	  <para>User account information.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><filename>/etc/shadow</filename></term>
	<listitem>
	  <para>Secure user account information.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><filename>/etc/login.defs</filename></term>
	<listitem>
	  <para>Shadow password suite configuration.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id='see_also'>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
	<refentrytitle>passwd</refentrytitle><manvolnum>1</manvolnum>
      </citerefentry>,
      <citerefentry>
	<refentrytitle>newusers</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
	<refentrytitle>useradd</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
	<refentrytitle>login.defs</refentrytitle><manvolnum>5</manvolnum>
      </citerefentry>.
    </para>
  </refsect1>
</refentry>