granicus.if.org Git - shadow/blob - man/passwd.1.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3    Copyright (c) 1989 - 1994, Julianne Frances Haugh
   4    Copyright (c) 2007 - 2009, Nicolas François
   5    All rights reserved.
   6
   7    Redistribution and use in source and binary forms, with or without
   8    modification, are permitted provided that the following conditions
   9    are met:
  10    1. Redistributions of source code must retain the above copyright
  11       notice, this list of conditions and the following disclaimer.
  12    2. Redistributions in binary form must reproduce the above copyright
  13       notice, this list of conditions and the following disclaimer in the
  14       documentation and/or other materials provided with the distribution.
  15    3. The name of the copyright holders or contributors may not be used to
  16       endorse or promote products derived from this software without
  17       specific prior written permission.
  18
  19    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  22    PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT
  23    HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30 -->
  31 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
  32   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  33 <!ENTITY ENCRYPT_METHOD        SYSTEM "login.defs.d/ENCRYPT_METHOD.xml">
  34 <!ENTITY MD5_CRYPT_ENAB        SYSTEM "login.defs.d/MD5_CRYPT_ENAB.xml">
  35 <!ENTITY OBSCURE_CHECKS_ENAB   SYSTEM "login.defs.d/OBSCURE_CHECKS_ENAB.xml">
  36 <!ENTITY PASS_ALWAYS_WARN      SYSTEM "login.defs.d/PASS_ALWAYS_WARN.xml">
  37 <!ENTITY PASS_CHANGE_TRIES     SYSTEM "login.defs.d/PASS_CHANGE_TRIES.xml">
  38 <!ENTITY PASS_MAX_LEN          SYSTEM "login.defs.d/PASS_MAX_LEN.xml">
  39 <!ENTITY SHA_CRYPT_MIN_ROUNDS  SYSTEM "login.defs.d/SHA_CRYPT_MIN_ROUNDS.xml">
  40 ]>
  41 <refentry id='passwd.1'>
  42   <!--  $Id$ -->
  43   <refmeta>
  44     <refentrytitle>passwd</refentrytitle>
  45     <manvolnum>1</manvolnum>
  46     <refmiscinfo class="sectdesc">User Commands</refmiscinfo>
  47   </refmeta>
  48   <refnamediv id='name'>
  49     <refname>passwd</refname>
  50     <refpurpose>change user password</refpurpose>
  51   </refnamediv>
  52
  53   <refsynopsisdiv id='synopsis'>
  54     <cmdsynopsis>
  55       <command>passwd</command>
  56       <arg choice='opt'>
  57         <replaceable>options</replaceable>
  58       </arg>
  59       <arg choice='opt'>
  60         <replaceable>LOGIN</replaceable>
  61       </arg>
  62     </cmdsynopsis>
  63   </refsynopsisdiv>
  64
  65   <refsect1 id='description'>
  66     <title>DESCRIPTION</title>
  67     <para>
  68       The <command>passwd</command> command changes passwords for user accounts.
  69       A normal user may only change the password for his/her own account, while
  70       the superuser may change the password for any account.
  71       <command>passwd</command> also changes the account or associated
  72       password validity period.
  73     </para>
  74
  75     <refsect2 id='password_changes'>
  76       <title>Password Changes</title>
  77       <para>
  78         The user is first prompted for his/her old password, if one is
  79         present. This password is then encrypted and compared against the
  80         stored password. The user has only one chance to enter the correct
  81         password. The superuser is permitted to bypass this step so that
  82         forgotten passwords may be changed.
  83       </para>
  84
  85       <para>
  86         After the password has been entered, password aging information is
  87         checked to see if the user is permitted to change the password at
  88         this time. If not, <command>passwd</command> refuses to change the
  89         password and exits.
  90       </para>
  91
  92       <para>
  93         The user is then prompted twice for a replacement password. The
  94         second entry is compared against the first and both are required to
  95         match in order for the password to be changed.
  96       </para>
  97
  98       <para>
  99         Then, the password is tested for complexity. As a general guideline,
 100         passwords should consist of 6 to 8 characters including one or more
 101         characters from each of the following sets:
 102       </para>
 103
 104       <itemizedlist mark='bullet'>
 105         <listitem>
 106           <para>lower case alphabetics</para>
 107         </listitem>
 108         <listitem>
 109           <para>digits 0 thru 9</para>
 110         </listitem>
 111         <listitem>
 112           <para>punctuation marks</para>
 113         </listitem>
 114       </itemizedlist>
 115
 116       <para>
 117         Care must be taken not to include the system default erase or kill
 118         characters. <command>passwd</command> will reject any password which
 119         is not suitably complex.
 120       </para>
 121
 122     </refsect2>
 123
 124     <refsect2 id='hints_for_user_passwords'>
 125       <title>Hints for user passwords</title>
 126       <para>
 127         The security of a password depends upon the strength of the
 128         encryption algorithm and the size of the key space. The legacy
 129         <emphasis>UNIX</emphasis> System encryption method is based on the
 130         NBS DES algorithm. More recent methods are now recommended (see
 131         <option>ENCRYPT_METHOD</option>). The size of the key space
 132         depends upon the randomness of the password which is selected.
 133       </para>
 134
 135       <para>
 136         Compromises in password security normally result from careless
 137         password selection or handling. For this reason, you should not
 138         select a password which appears in a dictionary or which must be
 139         written down. The password should also not be a proper name, your
 140         license number, birth date, or street address. Any of these may be
 141         used as guesses to violate system security.
 142       </para>
 143
 144       <para>
 145         You can find advices on how to choose a strong password on
 146         http://en.wikipedia.org/wiki/Password_strength
 147       </para>
 148     </refsect2>
 149   </refsect1>
 150
 151   <refsect1 id='options'>
 152     <title>OPTIONS</title>
 153     <para>
 154       The options which apply to the <command>passwd</command> command are:
 155     </para>
 156     <variablelist remap='IP'>
 157       <varlistentry>
 158         <term>
 159           <option>-a</option>, <option>--all</option>
 160         </term>
 161         <listitem>
 162           <para>
 163             This option can be used only with <option>-S</option> and causes show
 164             status for all users.
 165           </para>
 166         </listitem>
 167       </varlistentry>
 168       <varlistentry>
 169         <term>
 170           <option>-d</option>, <option>--delete</option>
 171         </term>
 172         <listitem>
 173           <para>
 174             Delete a user's password (make it empty). This is a quick way
 175             to disable a password for an account. It will set the named
 176             account passwordless.
 177           </para>
 178         </listitem>
 179       </varlistentry>
 180       <varlistentry>
 181         <term>
 182           <option>-e</option>, <option>--expire</option>
 183         </term>
 184         <listitem>
 185           <para>
 186             Immediately expire an account's password. This in effect can
 187             force a user to change his/her password at the user's next login.
 188           </para>
 189         </listitem>
 190       </varlistentry>
 191       <varlistentry>
 192         <term><option>-h</option>, <option>--help</option></term>
 193         <listitem>
 194           <para>Display help message and exit.</para>
 195         </listitem>
 196       </varlistentry>
 197       <varlistentry>
 198         <term>
 199           <option>-i</option>, <option>--inactive</option> <replaceable>INACTIVE</replaceable>
 200         </term>
 201         <listitem>
 202           <para>
 203             This option is used to disable an account after the password has
 204             been expired for a number of days. After a user account has had
 205             an expired password for <replaceable>INACTIVE</replaceable>
 206             days, the user may no longer sign on to the account.
 207           </para>
 208         </listitem>
 209       </varlistentry>
 210       <varlistentry>
 211         <term>
 212           <option>-k</option>, <option>--keep-tokens</option>
 213         </term>
 214         <listitem>
 215           <para>
 216             Indicate password change should be performed only for expired
 217             authentication tokens (passwords). The user wishes to keep their
 218             non-expired tokens as before.
 219           </para>
 220         </listitem>
 221       </varlistentry>
 222       <varlistentry>
 223         <term>
 224           <option>-l</option>, <option>--lock</option>
 225         </term>
 226         <listitem>
 227           <para>
 228             Lock the password of the named account. This option disables a
 229             password by changing it to a value which matches no possible
 230             encrypted value (it adds a ´!´ at the beginning of the
 231             password).
 232           </para>
 233           <para>
 234             Note that this does not disable the account. The user may
 235             still be able to login using another authentication token
 236             (e.g. an SSH key). To disable the account, administrators
 237             should use <command>usermod --expiredate 1</command> (this set
 238             the account's expire date to Jan 2, 1970).
 239           </para>
 240           <para>
 241             Users with a locked password are not allowed to change their
 242             password.
 243           </para>
 244         </listitem>
 245       </varlistentry>
 246       <varlistentry>
 247         <term>
 248           <option>-m</option>, <option>--mindays</option> <replaceable>MIN_DAYS</replaceable>
 249         </term>
 250         <listitem>
 251           <para>
 252             Set the minimum number of days between password changes to
 253             <replaceable>MIN_DAYS</replaceable>. A value of zero for this field
 254             indicates that the user may change his/her password at any time.
 255           </para>
 256         </listitem>
 257       </varlistentry>
 258       <varlistentry>
 259         <term>
 260           <option>-q</option>, <option>--quiet</option>
 261         </term>
 262         <listitem>
 263           <para>
 264             Quiet mode.
 265           </para>
 266         </listitem>
 267       </varlistentry>
 268       <varlistentry>
 269         <term>
 270           <option>-r</option>, <option>--repository</option> <replaceable>REPOSITORY</replaceable>
 271         </term>
 272         <listitem>
 273           <para>
 274             change password in <replaceable>REPOSITORY</replaceable> repository
 275           </para>
 276         </listitem>
 277       </varlistentry>
 278       <varlistentry>
 279         <term>
 280           <option>-S</option>, <option>--status</option>
 281         </term>
 282         <listitem>
 283           <para>
 284             Display account status information. The status information
 285             consists of 7 fields. The first field is the user's login name.
 286             The second field indicates if the user account has a locked
 287             password (L),
 288             has no password (NP), or has a usable password (P). The third
 289             field gives the date of the last password change. The next four
 290             fields are the minimum age, maximum age, warning period, and
 291             inactivity period for the password. These ages are expressed in
 292             days.
 293           </para>
 294         </listitem>
 295       </varlistentry>
 296       <varlistentry>
 297         <term>
 298           <option>-u</option>, <option>--unlock</option>
 299         </term>
 300         <listitem>
 301           <para>
 302             Unlock the password of the named account. This option
 303             re-enables a password by changing the password back to its
 304             previous value (to the value before using the
 305             <option>-l</option> option).
 306           </para>
 307         </listitem>
 308       </varlistentry>
 309       <varlistentry>
 310         <term>
 311           <option>-w</option>, <option>--warndays</option> <replaceable>WARN_DAYS</replaceable>
 312         </term>
 313         <listitem>
 314           <para>
 315             Set the number of days of warning before a password change is
 316             required. The <replaceable>WARN_DAYS</replaceable> option is
 317             the number of days prior to the password expiring that a user
 318             will be warned that his/her password is about to expire.
 319           </para>
 320         </listitem>
 321       </varlistentry>
 322       <varlistentry>
 323         <term>
 324           <option>-x</option>, <option>--maxdays</option> <replaceable>MAX_DAYS</replaceable>
 325         </term>
 326         <listitem>
 327           <para>
 328             Set the maximum number of days a password remains valid. After
 329             <replaceable>MAX_DAYS</replaceable>, the password is required
 330             to be changed.
 331           </para>
 332         </listitem>
 333       </varlistentry>
 334     </variablelist>
 335   </refsect1>
 336
 337   <refsect1 id='caveats'>
 338     <title>CAVEATS</title>
 339     <para>
 340       Password complexity checking may
 341       vary from site to site. The user is urged to select a password as
 342       complex as he or she feels comfortable with.
 343     </para>
 344     <para>
 345       Users may not be able to
 346       change their password on a system if NIS is enabled and they are not
 347       logged into the NIS server.
 348     </para>
 349     <para condition="pam">
 350       <command>passwd</command> uses PAM to authenticate users and to
 351       change their passwords.
 352     </para>
 353   </refsect1>
 354
 355   <refsect1 id='configuration' condition="no_pam">
 356     <title>CONFIGURATION</title>
 357     <para>
 358       The following configuration variables in
 359       <filename>/etc/login.defs</filename> change the behavior of this
 360       tool:
 361     </para>
 362     <variablelist>
 363       &ENCRYPT_METHOD;
 364       &MD5_CRYPT_ENAB;
 365       &OBSCURE_CHECKS_ENAB;
 366       &PASS_ALWAYS_WARN;
 367       &PASS_CHANGE_TRIES;
 368       &PASS_MAX_LEN; <!-- documents also PASS_MIN_LEN -->
 369       &SHA_CRYPT_MIN_ROUNDS;
 370     </variablelist>
 371   </refsect1>
 372
 373   <refsect1 id='files'>
 374     <title>FILES</title>
 375     <variablelist>
 376       <varlistentry>
 377         <term><filename>/etc/passwd</filename></term>
 378         <listitem>
 379           <para>User account information.</para>
 380         </listitem>
 381       </varlistentry>
 382       <varlistentry>
 383         <term><filename>/etc/shadow</filename></term>
 384         <listitem>
 385           <para>Secure user account information.</para>
 386         </listitem>
 387       </varlistentry>
 388       <varlistentry condition="no_pam">
 389         <term><filename>/etc/login.defs</filename></term>
 390         <listitem>
 391           <para>Shadow password suite configuration.</para>
 392         </listitem>
 393       </varlistentry>
 394       <varlistentry condition="pam">
 395         <term><filename>/etc/pam.d/passwd</filename></term>
 396         <listitem>
 397           <para>PAM configuration for <command>passwd</command>.</para>
 398         </listitem>
 399       </varlistentry>
 400     </variablelist>
 401   </refsect1>
 402
 403   <refsect1 id='exit_values'>
 404     <title>EXIT VALUES</title>
 405     <para>
 406       The <command>passwd</command> command exits with the following values:
 407       <variablelist>
 408         <varlistentry>
 409           <term><replaceable>0</replaceable></term>
 410           <listitem>
 411             <para>success</para>
 412           </listitem>
 413         </varlistentry>
 414         <varlistentry>
 415           <term><replaceable>1</replaceable></term>
 416           <listitem>
 417             <para>permission denied</para>
 418           </listitem>
 419         </varlistentry>
 420         <varlistentry>
 421           <term><replaceable>2</replaceable></term>
 422           <listitem>
 423             <para>invalid combination of options</para>
 424             </listitem>
 425         </varlistentry>
 426         <varlistentry>
 427           <term><replaceable>3</replaceable></term>
 428           <listitem>
 429             <para>unexpected failure, nothing done</para>
 430           </listitem>
 431         </varlistentry>
 432         <varlistentry>
 433           <term><replaceable>4</replaceable></term>
 434           <listitem>
 435             <para>unexpected failure, <filename>passwd</filename> file missing</para>
 436           </listitem>
 437         </varlistentry>
 438         <varlistentry>
 439           <term><replaceable>5</replaceable></term>
 440           <listitem>
 441             <para><filename>passwd</filename> file busy, try again</para>
 442           </listitem>
 443         </varlistentry>
 444         <varlistentry>
 445           <term><replaceable>6</replaceable></term>
 446           <listitem>
 447             <para>invalid argument to option</para>
 448           </listitem>
 449         </varlistentry>
 450       </variablelist>
 451     </para>
 452   </refsect1>
 453
 454   <refsect1 id='see_also'>
 455     <title>SEE ALSO</title>
 456     <para>
 457       <citerefentry>
 458         <refentrytitle>passwd</refentrytitle><manvolnum>5</manvolnum>
 459       </citerefentry>,
 460       <citerefentry>
 461         <refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum>
 462       </citerefentry>,
 463       <phrase condition="no_pam">
 464         <citerefentry>
 465           <refentrytitle>login.defs</refentrytitle><manvolnum>5</manvolnum>
 466         </citerefentry>,
 467       </phrase>
 468       <citerefentry>
 469         <refentrytitle>usermod</refentrytitle><manvolnum>8</manvolnum>
 470       </citerefentry>.
 471     </para>
 472   </refsect1>
 473 </refentry>