shadow/man/chpasswd.8.xml

289 lines
8.8 KiB
XML
Raw Normal View History

<?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. Default
encryption algorithm is DES. 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>