DomainKey-Signature: a=rsa-sha1; c=nofws; d=sourceware.org; h=list-id
	:list-unsubscribe:list-subscribe:list-archive:list-post
	:list-help:sender:date:from:reply-to:message-id:to:subject
	:in-reply-to:references:mime-version:content-type; q=dns; s=
	default; b=E+qNVcKUuVXE1Ri/SL2YOPt+zTdih53ELfsychw/1tPbh4RfgN+1V
	MtXc2iAtcZTxG4523UjL8NiTnZL7Fv3qkZ82Un8vu3joFN4NPPJtTjzV3tC4/tgp
	EAoIdDO+ekKn+U6p53PxaGB1JitUQJhmy93Px0oYGOh2Qns3/q/MqY=
Mailing-List: contact cygwin-help AT cygwin DOT com; run by ezmlm
Sender: cygwin-owner AT cygwin DOT com
Mail-Followup-To: cygwin AT cygwin DOT com
Date: Wed, 6 Aug 2014 21:21:15 +0400
From: Andrey Repin <anrdaemon AT yandex DOT ru>
Reply-To: cygwin AT cygwin DOT com
Message-ID: <224522274.20140806212115@yandex.ru>
To: Corinna Vinschen <cygwin AT cygwin DOT com>
Subject: Re: cannot display man page for /bin/passwd
In-Reply-To: <20140805082102.GD2868@calimero.vinschen.de>
References: <CAJ1FpuPVvp89xTW4xVH1VpLFYg0Wgr8FNB9OsDYh=hubgsZnDQ AT mail DOT gmail DOT com> <20140805082102 DOT GD2868 AT calimero DOT vinschen DOT de>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="----------261E0ED3C24852A"

------------261E0ED3C24852A
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

Greetings, Corinna Vinschen!

>> When I try to display the man page for /bin/passwd, the man page for
>> the openssl passwd subcommand is displayed.
>> 
>> It appears that both the package containing /bin/passwd, and the
>> openssl package place the passwd.1.gz file in the /usr/share/man/man1
>> directory, so that only the man page from the most recently installed
>> package is displayed.

> No, the Cygwin passwd tool has no man page.

That's sad. Can we change it?

> The documentation is only in the User's Guide:
> https://cygwin.com/cygwin-ug-net/using-utils.html#passwd

While reading the page, I've noticed a discrepancy in options synopsis
and further description of the tool operation.
Namely, options --minage, --maxage parameter spelled as "DAYS", while down the
text they are referred to as MINDAYS and MAXDAYS.
I suggest changing the options description to match the text, as that it'll
make more sense.

Also, the paragraph "All operations affecting the current user" is missing a
"$" sign in reference to environment variable LOGONSERVER.

The phrase "to enter a password which" is probably missing a comma.

Other question is relevance of a requirement "to run cygserver as a service
under the LocalSystem account" for modern times.

Slightly unrelated question. I've noticed, that if a paragraph in source file
have line break after a period, the page is rendered with two spaces between
a period and first letter of next sentence, even though there's only one
character (a linefeed) exists. No stray spaces, no CR's. Is this intended?

The latter issue can be demonstrated with this little sample:

echo -e ".TH test 1\n.SH NAME\nJust\ntwo.\nSpaces.\n" | man -l -


--
WBR,
Andrey Repin (anrdaemon AT yandex DOT ru) 05.08.2014, <14:58>

Sorry for my terrible english...
------------261E0ED3C24852A
Content-Type: application/octet-stream; name="passwd.1"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: attachment; filename="passwd.1"

.TH passwd 1 2014-08-05 Cygwin "Cygwin documentation"=0A=
=0A=
.SH NAME=0A=
passwd \- Change user's password or password attributes.=0A=
=0A=
.SH SYNOPSIS=0A=
.B passwd=0A=
.RI [ OPTION ]\ [ USER ]=0A=
=0A=
.SH OPTIONS=0A=
=0A=
.SS User operations:=0A=
.TP 26em=0A=
.BR \-l , \--lock=0A=
lock=0A=
.IR USER 's=0A=
account.=0A=
.TP=0A=
.BR \-u , \--unlock=0A=
unlock=0A=
.IR USER 's=0A=
account.=0A=
.TP=0A=
.BR \-c , \--cannot-change=0A=
.I USER=0A=
can't change password.=0A=
.TP=0A=
.BR \-C , \--can-change=0A=
.I USER=0A=
can change password.=0A=
.TP=0A=
.BR \-e , \--never-expires=0A=
.IR USER 's=0A=
password never expires.=0A=
.TP=0A=
.BR \-E , \--expires=0A=
.IR USER 's=0A=
password expires according to system's password aging rule.=0A=
.TP=0A=
.BR \-p , \--pwd-not-required=0A=
no password required for=0A=
.IR USER \.=0A=
.TP=0A=
.BR \-P , \--pwd-required=0A=
password is required for=0A=
.IR USER \.=0A=
.TP=0A=
.BR \-R , \--reg-store-pwd=0A=
enter password to store it in the registry for later usage by services to b=
e able to switch to this user context with network credentials.=0A=
=0A=
.SS System operations:=0A=
.TP 26em=0A=
.BR \-i , "--inactive \fINUM"=0A=
set=0A=
.I NUM=0A=
of days before inactive accounts are disabled (inactive accounts are those =
with expired passwords).=0A=
.TP=0A=
.BR \-n , "--minage \fIMINDAYS"=0A=
set system minimum password age to=0A=
.I MINDAYS=0A=
days.=0A=
.TP=0A=
.BR \-x , "--maxage \fIMAXDAYS"=0A=
set system maximum password age to=0A=
.I MAXDAYS=0A=
days.=0A=
.TP=0A=
.BR \-L , "--length \fILEN"=0A=
set system minimum password length to=0A=
.IR LEN \.=0A=
=0A=
.SS Other options:=0A=
.TP 26em=0A=
.BR \-d , "--logonserver \fISERVER"=0A=
connect to=0A=
.I SERVER=0A=
(e.g. domain controller).=0A=
Default server is the local system, unless changing the current user, in wh=
ich case the default is the content of=0A=
.IR $LOGONSERVER \.=0A=
.TP=0A=
.BR \-S , \--status=0A=
display password status for=0A=
.I USER=0A=
(locked, expired, etc.) plus global system password settings.=0A=
.TP=0A=
.BR \-h , \--help=0A=
output usage information and exit.=0A=
.TP=0A=
.BR \-V , \--version=0A=
output version information and exit.=0A=
=0A=
.SH DESCRIPTION=0A=
.PP=0A=
.B passwd=0A=
changes passwords for user accounts. A normal user may only change the pass=
word for their own account,=0A=
but administrators may change passwords on any account.=0A=
.B passwd=0A=
also changes account information, such as password expiry dates and interva=
ls.=0A=
.PP=0A=
If no option is given, change of a=0A=
.IR USER 's=0A=
password is initiated. If no user name is given, operate on current user.=
=0A=
.PP=0A=
System operations must not be mixed with user operations. Don't specify a=
=0A=
.I USER=0A=
when triggering a system operation.=0A=
.PP=0A=
Don't specify a user or any other option together with the=0A=
.B \-R=0A=
option. Non-Admin users can only store their password if cygserver is runni=
ng. Note that storing even obfuscated passwords=0A=
in the registry is not overly secure. Use this feature only if the machine =
is adequately locked down. Don't use this feature=0A=
if you don't need network access within a remote session. You can delete yo=
ur stored password by using=0A=
.RB \' "passwd \-R" \'=0A=
and specifying an empty password.=0A=
.SS Changing password=0A=
.PP=0A=
For password changes, the user is first prompted for their old password, if=
 one is present. This password is then encrypted and=0A=
compared against the stored password. The user has only one chance to enter=
 the correct password. The administrators are=0A=
permitted to bypass this step so that forgotten passwords may be changed.=
=0A=
.PP=0A=
The user is then prompted for a replacement password.=0A=
.B passwd=0A=
will prompt twice for this replacement and compare the second entry against=
 the first.=0A=
Both entries are required to match in order for the password to be changed.=
=0A=
.PP=0A=
After the password has been entered, password aging information is checked =
to see if the user is permitted to change their=0A=
password at this time. If not, passwd refuses to change the password and ex=
its.=0A=
.SS Other options=0A=
.PP=0A=
To get current password status information, use the=0A=
.B \-S=0A=
option. Administrators can use=0A=
.B passwd=0A=
to perform several account maintenance functions (users may perform some of=
 these functions=0A=
on their own accounts). Accounts may be locked with the=0A=
.B \-l=0A=
flag and unlocked with the=0A=
.B \-u=0A=
flag. Similarly,=0A=
.B \-c=0A=
disables a user's ability to change passwords, and=0A=
.B \-C=0A=
allows a user to change passwords. For password expiry, the=0A=
.B \-e=0A=
option disables expiration, while the=0A=
.B \-E=0A=
option causes the password to expire according to the system's normal aging=
 rules. Use=0A=
.B \-p=0A=
to disable the password requirement for a user, or=0A=
.B \-P=0A=
to require a password.=0A=
.PP=0A=
Administrators can also use=0A=
.B passwd=0A=
to change system-wide password expiry and length requirements with the=0A=
.BR \-i ", "  \-n ", "  \-x ", and " \-L \ options.=0A=
The=0A=
.B \-i=0A=
option is used to disable an account after the password has been expired fo=
r a number of days.=0A=
After a user account has had an expired password for=0A=
.I NUM=0A=
days, the user may no longer sign on to the account. The=0A=
.B \-n=0A=
option is used to set the minimum number of days before a password may be c=
hanged.=0A=
The user will not be permitted to change the password until=0A=
.I MINDAYS=0A=
days have elapsed. The=0A=
.B \-x=0A=
option is used to set the maximum number of days a password remains valid. =
After=0A=
.I MAXDAYS=0A=
days, the password is required to be changed. Allowed values for the above =
options are=0A=
.IR 0 " to " 999 \.=0A=
.RB "The " \-L=0A=
option sets the minimum length of allowed passwords for users who don't bel=
ong to the administrators group to=0A=
.I LEN=0A=
characters. Allowed values for the minimum password length are=0A=
.IR 0 " to " 14 \.=0A=
In any of the above cases, a value of=0A=
.I 0=0A=
means 'no restrictions'.=0A=
.PP=0A=
All operations affecting the current user are by default run against the lo=
gon server of the current user (taken from the=0A=
environment variable=0A=
.IR $LOGONSERVER \.=0A=
When password or account information of other users should be changed, the =
default server is the local system. To change a user=0A=
account on a remote machine, use the=0A=
.B \-d=0A=
option to specify the machine to run the command against. Note that the cur=
rent user must be a valid member of the=0A=
administrators group on the remote machine to perform such actions.=0A=
=0A=
.SS Storing password for network access=0A=
.PP=0A=
Users can use the=0A=
.RB \' "passwd \-R" \'=0A=
to enter a password, which then gets stored in a special area of the regist=
ry on the local system, which is also used by Windows=0A=
to store passwords of accounts running Windows services. When a privileged =
Cygwin application calls the=0A=
.BR set { e } uid ( \fIuser_id )=0A=
system call, Cygwin checks if a password for that user has been stored in t=
his registry area. If so, it uses this password to=0A=
switch to this user account using that password. This allows you to logon t=
hrough, for instance, ssh with public key=0A=
authentication and get a full qualified user token with all credentials for=
 network access. However,=0A=
.IR "the method has some drawbacks security-wise" \.=0A=
This is explained in more detail in the section called=0A=
.UR https://\:cygwin.com/\:cygwin-ug-net/\:ntsec.html=0A=
=E2=80=9CUsing Windows security in Cygwin=E2=80=9D=0A=
.UE \.=0A=
.PP=0A=
Please note that=0A=
.I=0A=
storing passwords in that registry area is a privileged operation=0A=
which only administrative accounts are allowed to do. Administrators can en=
ter the password for other user accounts into the=0A=
registry by specifying the username on the commandline. If normal, non-admi=
n users should be allowed to enter their passwords=0A=
using=0A=
.RB \' "passwd \-R" \',=0A=
it's required to run=0A=
.B cygserver=0A=
as a service under the=0A=
.I LocalSystem=0A=
account before running=0A=
.RB \' "passwd \-R" \'.=0A=
This only affects storing passwords. Using passwords in privileged processe=
s does not require cygserver to run.=0A=
=0A=
.SH LIMITATIONS=0A=
Users may not be able to change their password on some systems.=0A=
=0A=
.SH SEE ALSO=0A=
.BR cygserver (8)=0A=
=0A=


------------261E0ED3C24852A
Content-Type: text/plain; charset=us-ascii

--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
------------261E0ED3C24852A--