.\" Copyright Red Hat, Inc., 1998, 1999, 2002, 2009, 2012, 2015, 2018.

.\"

.\" Redistribution and use in source and binary forms, with or without

.\" modification, are permitted provided that the following conditions

.\" are met:

.\" 1. Redistributions of source code must retain the above copyright

.\"    notice, and the entire permission notice in its entirety,

.\"    including the disclaimer of warranties.

.\" 2. Redistributions in binary form must reproduce the above copyright

.\"    notice, this list of conditions and the following disclaimer in the

.\"    documentation and/or other materials provided with the distribution.

.\" 3. The name of the author may not be used to endorse or promote

.\"    products derived from this software without specific prior

.\"    written permission.

.\"

.\" ALTERNATIVELY, this product may be distributed under the terms of

.\" the GNU Public License, in which case the provisions of the GPL are

.\" required INSTEAD OF the above restrictions.  (This clause is

.\" necessary due to a potential bad interaction between the GPL and

.\" the restrictions contained in a BSD-style copyright.)

.\"

.\"  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED

.\" WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES

.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

.\" DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,

.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES

.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR

.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,

.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)

.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED

.\" OF THE POSSIBILITY OF SUCH DAMAGE.

.\"

.\" Copyright (c) Cristian Gafton, 1998, <gafton@redhat.com>

.\" Copyright (c) Tomas Mraz, 2009, 2012, <tmraz@redhat.com>

.\"

.TH PASSWD 1 "Mar 28 2018" "GNU/Linux" "User utilities"

.SH NAME

passwd \- update user's authentication tokens

.SH SYNOPSIS

.B passwd [-k] [-l] [-u [-f]] [-d] [-e] [-n mindays] [-x maxdays] [-w warndays] [-i inactivedays] [-S] [--stdin] [username]

.sp 2

.SH DESCRIPTION

The passwd utility is used to update user's authentication token(s).

This task is achieved through calls to the

.BR "Linux-PAM" " and "

.BR "Libuser API" ". "

Essentially, it initializes itself as a "passwd" service with

.I Linux-PAM

and utilizes configured

.I "password"

modules to authenticate and then update a user's password.

.sp

A simple entry in the global

.I Linux-PAM

configuration file for this service would be:

.br

.br

 #

.br

 # passwd service entry that does strength checking of

.br

 # a proposed password before updating it.

.br

 #

.br

 passwd password requisite pam_cracklib.so retry=3

.br

 passwd password required pam_unix.so use_authtok

.br

 #

.sp

Note, other module types are not required for this application to

function correctly.

.SH OPTIONS

.TP

\fB\-k\fR, \fB\-\-keep\fR

The option

.B \-k

is used to indicate that the update should only be for expired

authentication tokens (passwords); the user wishes to keep their

non-expired tokens as before.

.TP

\fB\-l\fR, \fB\-\-lock\fP

This option is used to lock the password of specified account and

it is available to root only. The locking is performed by rendering

the encrypted password into an invalid string (by prefixing the

encrypted string with an !). Note that the account is not fully

locked - the user can still log in by other means of authentication

such as the ssh public key authentication. Use \fBchage -E 0 user\fR

command instead for full account locking.

.IP \fB--stdin\fR

This option is used to indicate that \fBpasswd\fR should read the new

password from standard input, which can be a pipe.

.TP

\fB\-u\fR, \fB\-\-unlock\fR

This is the reverse of the

.BR -l " option - it will unlock the account"

password by removing the ! prefix. This option is available to root

only. By default passwd will refuse to create a passwordless account 

(it will not unlock an account that has only "!" as a password). The 

force option \fB-f\fR will override this protection.

.TP

\fB\-d\fR, \fB\-\-delete\fR

This is a quick way to delete a password for an account. It will set

the named account passwordless. Available to root only.

Note that if the password was locked,

this implicitly removes the password lock as well.

.TP

\fB\-e\fR, \fB\-\-expire\fR

This is a quick way to expire a password for an account. The user will be

forced to change the password during the next login attempt.

Available to root only.

.TP

\fB\-f\fR, \fB\-\-force\fR

Force the specified operation.

.TP

\fB\-n\fR, \fB\-\-minimum\fR \fIDAYS\fR

This will set the minimum password lifetime, in days, if the user's

account supports password lifetimes.  Available to root only.

.TP

\fB\-x\fR, \fB\-\-maximum\fR \fIDAYS\fR

This will set the maximum password lifetime, in days, if the user's

account supports password lifetimes.  Available to root only.

.TP

\fB\-w\fR, \fB\-\-warning\fR \fIDAYS\fR

This will set the number of days in advance the user will begin receiving

warnings that her password will expire, if the user's account supports

password lifetimes.  Available to root only.

.TP

\fB\-i\fR, \fB\-\-inactive\fR \fIDAYS\fR

This will set the number of days which will pass before an expired password

for this account will be taken to mean that the account is inactive and should

be disabled, if the user's account supports password lifetimes.  Available to

root only.

.TP

\fB\-S\fR, \fB\-\-status\fR

This will output a short information about the status of the password

for a given account. The status information consists of 7 fields. The

first field is the user's login name. The second field indicates if the

user account has a locked password (L), has no password (NP), or has a

usable password (P). The third field gives the date of the last password

change. The next four fields are the minimum age, maximum age, warning

period, and inactivity period for the password. These ages are expressed

in days.

.sp

\fBNotes:\fR

The date of the last password change is stored as a number of days

since epoch. Depending on the current time zone, the

\fBpasswd \-S\fR

\fIusername\fR

may show the date of the last password change that is different

from the real date of the last password change by ±1 day.

.sp

This option is available to root only.

.SH "Remember the following two principles"

.IP \fBProtect\ your\ password.\fR

Don't write down your password - memorize it.

In particular, don't write it down and leave it anywhere, and don't

place it in an unencrypted file!  Use unrelated passwords for

systems controlled by different organizations.  Don't give or share your

password, in particular to someone claiming to be from

computer support or a vendor.  Don't let anyone watch you enter your

password.  Don't enter your password to a computer you don't trust or

if things "look funny"; someone may be trying to hijack your password.

Use the password for a limited time and change it periodically.

.IP \fBChoose\ a\ hard-to-guess\ password.\fR

.I passwd

through the calls to the

.BR pam_cracklib " PAM module"

will try to prevent you from choosing a really bad password,

but it isn't foolproof; create your password wisely.

Don't use something you'd find in a dictionary (in any language or jargon).

Don't use a name (including that of a spouse, parent, child, pet,

fantasy character, famous person, and location) or any

variation of your personal or account name.  Don't use accessible

information about you (such as your phone number, license plate, or

social security number) or your environment.  Don't use a birthday or a

simple pattern (such as "qwerty", "abc", or "aaa").  Don't use any of those

backwards, followed by a digit, or preceded by a digit. Instead, use

a mixture of upper and lower case letters, as well as digits or

punctuation.  When choosing a new password, make sure it's unrelated

to any previous password. Use long passwords (say at least 8 characters

long).  You might use a word pair with punctuation inserted, a

passphrase (an understandable sequence of words), or the first

letter of each word in a passphrase.

.SH ""

These principles are partially enforced by the system, but only partly so.

Vigilance on your part will make the system much more secure.

.SH "EXIT CODE"

The

.B passwd

command exits with the following codes:

.PP

\fI0\fR

.RS 4

success

.RE

.PP

\fI1\fR

.RS 4

passwd/libuser operation failed

.RE

.PP

\fI2\fR

.RS 4

unknown user

.RE

.PP

\fI252\fR

.RS 4

unknown user name

.RE

.PP

\fI253\fR

.RS 4

bad arguments or passwordless account

.RE

.PP

\fI254\fR

.RS 4

invalid application of arguments

.RE

.PP

\fI255\fR

.RS 4

libuser operation failed

.RE

.PP

Error messages are written to the standard error stream.

.SH "CONFORMING TO"

.br

.BR Linux-PAM

(Pluggable Authentication modules for Linux).

.SH "FILES"

.br

.B /etc/pam.d/passwd

- the

.BR Linux-PAM

configuration file

.SH BUGS

.sp 2

None known.

.SH "SEE ALSO"

.BR pam "(8), "

.BR pam.d "(5), "

.BR libuser.conf "(5), "

and

.BR pam_chauthtok "(3). "

.sp

For more complete information on how to configure this application

with

.BR Linux-PAM ", "

see the

.BR "Linux-PAM System Administrators' Guide" "."

.SH AUTHOR

Cristian Gafton <gafton@redhat.com>