chiark / gitweb /
wip manpage
[inn-innduct.git] / doc / man / ckpasswd.8
1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
26 .\" Set up some character translations and predefined strings.  \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
32 .tr \(*W-
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 .    ds -- \(*W-
36 .    ds PI pi
37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
39 .    ds L" ""
40 .    ds R" ""
41 .    ds C` ""
42 .    ds C' ""
43 'br\}
44 .el\{\
45 .    ds -- \|\(em\|
46 .    ds PI \(*p
47 .    ds L" ``
48 .    ds R" ''
49 'br\}
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .if \nF \{\
56 .    de IX
57 .    tm Index:\\$1\t\\n%\t"\\$2"
58 ..
59 .    nr % 0
60 .    rr F
61 .\}
62 .\"
63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
65 .hy 0
66 .if n .na
67 .\"
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
70 .    \" fudge factors for nroff and troff
71 .if n \{\
72 .    ds #H 0
73 .    ds #V .8m
74 .    ds #F .3m
75 .    ds #[ \f1
76 .    ds #] \fP
77 .\}
78 .if t \{\
79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 .    ds #V .6m
81 .    ds #F 0
82 .    ds #[ \&
83 .    ds #] \&
84 .\}
85 .    \" simple accents for nroff and troff
86 .if n \{\
87 .    ds ' \&
88 .    ds ` \&
89 .    ds ^ \&
90 .    ds , \&
91 .    ds ~ ~
92 .    ds /
93 .\}
94 .if t \{\
95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101 .\}
102 .    \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 .    \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 .    \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
117 \{\
118 .    ds : e
119 .    ds 8 ss
120 .    ds o a
121 .    ds d- d\h'-1'\(ga
122 .    ds D- D\h'-1'\(hy
123 .    ds th \o'bp'
124 .    ds Th \o'LP'
125 .    ds ae ae
126 .    ds Ae AE
127 .\}
128 .rm #[ #] #H #V #F C
129 .\" ========================================================================
130 .\"
131 .IX Title "CKPASSWD 8"
132 .TH CKPASSWD 8 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
133 .SH "NAME"
134 ckpasswd \- nnrpd password authenticator
135 .SH "SYNOPSIS"
136 .IX Header "SYNOPSIS"
137 \&\fBckpasswd\fR [\fB\-gs\fR] [\fB\-d\fR \fIdatabase\fR] [\fB\-f\fR \fIfilename\fR]
138 [\fB\-u\fR \fIusername\fR \fB\-p\fR \fIpassword\fR]
139 .SH "DESCRIPTION"
140 .IX Header "DESCRIPTION"
141 \&\fBckpasswd\fR is the basic password authenticator for nnrpd, suitable for
142 being run from an auth stanza in \fIreaders.conf\fR.  See \fIreaders.conf\fR\|(5) for
143 more information on how to configure an nnrpd authenticator.
144 .PP
145 \&\fBckpasswd\fR accepts a username and password from nnrpd and tells \fInnrpd\fR\|(8)
146 whether that's the correct password for that username.  By default, when
147 given no arguments, it tries to check the password using \s-1PAM\s0 if support
148 for \s-1PAM\s0 was found when \s-1INN\s0 was built.  Failing that, it tries to check the
149 password against the password field returned by \fIgetpwnam\fR\|(3).  Note that
150 these days most systems no longer make real passwords available via
151 \&\fIgetpwnam\fR\|(3) (some still do if and only if the program calling \fIgetpwnam\fR\|(3)
152 is running as root).
153 .PP
154 When using \s-1PAM\s0, \fBckpasswd\fR identifies itself as \f(CW\*(C`nnrpd\*(C'\fR, not as
155 \&\f(CW\*(C`ckpasswd\*(C'\fR, and the \s-1PAM\s0 configuration must be set up accordingly.  The
156 details of \s-1PAM\s0 configuration are different on different operating systems
157 (and even different Linux distributions); see \s-1EXAMPLES\s0 below for help
158 getting started, and look for a \fIpam\fR\|(7) or \fIpam.conf\fR\|(4) manual page on your
159 system.
160 .PP
161 When using any method other than \s-1PAM\s0, \fBckpasswd\fR expects all passwords to
162 be stored encrypted by the system \fIcrypt\fR\|(3) function and calls \fIcrypt\fR\|(3) on
163 the supplied password before comparing it to the expected password.  \s-1IF\s0
164 you're using a different password hash scheme (like \s-1MD5\s0), you must use
165 \&\s-1PAM\s0.
166 .SH "OPTIONS"
167 .IX Header "OPTIONS"
168 .IP "\fB\-d\fR \fIdatabase\fR" 4
169 .IX Item "-d database"
170 Read passwords from a database (ndbm or dbm format depending on what your
171 system has) rather than by using \fIgetpwnam\fR\|(3).  \fBckpasswd\fR expects
172 \&\fIdatabase\fR.dir and \fIdatabase\fR.pag to exist and to be a database keyed by
173 username with the encrypted passwords as the values.
174 .Sp
175 While \s-1INN\s0 doesn't come with a program intended specifically to create such
176 databases, on most systems it's fairly easy to write a Perl script to do
177 so.  Something like:
178 .Sp
179 .Vb 16
180 \&    #!/usr/bin/perl
181 \&    use NDBM_File;
182 \&    use Fcntl;
183 \&    tie (%db, 'NDBM_File', '/path/to/database', O_RDWR|O_CREAT, 0640)
184 \&        or die "Cannot open /path/to/database: $!\en";
185 \&    $| = 1;
186 \&    print "Username: ";
187 \&    my $user = <STDIN>;
188 \&    chomp $user;
189 \&    print "Password: ";
190 \&    my $passwd = <STDIN>;
191 \&    chomp $passwd;
192 \&    my @alphabet = ('.', '/', 0..9, 'A'..'Z', 'a'..'z');
193 \&    my $salt = join '', @alphabet[rand 64, rand 64];
194 \&    $db{$user} = crypt ($passwd, $salt);
195 \&    untie %db;
196 .Ve
197 .Sp
198 Note that this will echo back the password when typed; there are obvious
199 improvements that could be made to this, but it should be a reasonable
200 start.  Sometimes a program like this will be available with the name
201 \&\fBdbmpasswd\fR.
202 .Sp
203 This option will not be available on systems without dbm or ndbm
204 libraries.
205 .IP "\fB\-f\fR \fIfilename\fR" 4
206 .IX Item "-f filename"
207 Read passwords from the given file rather than using \fIgetpwnam\fR\|(3).  The
208 file is expected to be formatted like a system password file, at least
209 vaguely.  That means each line should look something like:
210 .Sp
211 .Vb 1
212 \&    username:pdIh9NCNslkq6
213 .Ve
214 .Sp
215 (and each line may have an additional colon after the encrypted password
216 and additional data; that data will be ignored by \fBckpasswd\fR).  Lines
217 starting with a number sign (`#') are ignored.  \s-1INN\s0 does not come with a
218 utility to create the encrypted passwords, but \fBhtpasswd\fR (which comes
219 with Apache) can do so and it's a quick job with Perl (see the example
220 script under \fB\-d\fR).  If using Apache's \fBhtpasswd\fR program, be sure to
221 give it the \fB\-d\fR option so that it will use \fIcrypt\fR\|(3).
222 .IP "\fB\-g\fR" 4
223 .IX Item "-g"
224 Attempt to look up system group corresponding to username and return a
225 string like \*(L"user@group\*(R" to be matched against in \fIreaders.conf\fR.  This
226 option is incompatible with the \fB\-d\fR and \fB\-f\fR options.
227 .IP "\fB\-p\fR \fIpassword\fR" 4
228 .IX Item "-p password"
229 Use \fIpassword\fR as the password for authentication rather than reading a
230 password using the nnrpd authenticator protocol.  This option is useful
231 only for testing your authentication system (particularly since it
232 involves putting a password on the command line), and does not work when
233 \&\fBckpasswd\fR is run by \fBnnrpd\fR.  If this option is given, \fB\-u\fR must also
234 be given.
235 .IP "\fB\-s\fR" 4
236 .IX Item "-s"
237 Check passwords against the result of \fIgetspnam\fR\|(3) instead of \fIgetpwnam\fR\|(3).
238 This function, on those systems that supports it, reads from /etc/shadow
239 or similar more restricted files.  If you want to check passwords supplied
240 to \fInnrpd\fR\|(8) against system account passwords, you will probably have to
241 use this option on most systems.
242 .Sp
243 Most systems require special privileges to call \fIgetspnam\fR\|(3), so in order
244 to use this option you may need to make \fBckpasswd\fR setgid to some group
245 (like group \*(L"shadow\*(R") or even setuid root.  \fBckpasswd\fR has not been
246 specifically audited for such uses!  It is, however, a very small program
247 that you should be able to check by hand for security.
248 .Sp
249 This configuration is not recommended if it can be avoided, for serious
250 security reasons.  See \*(L"\s-1SECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" in readers.conf\&(5) for
251 discussion.
252 .IP "\fB\-u\fR \fIusername\fR" 4
253 .IX Item "-u username"
254 Authenticate as \fIusername\fR.  This option is useful only for testing (so
255 that you can test your authentication system easily) and does not work
256 when \fBckpasswd\fR is run by \fBnnrpd\fR.  If this option is given, \fB\-p\fR must
257 also be given.
258 .SH "EXAMPLES"
259 .IX Header "EXAMPLES"
260 See \fIreaders.conf\fR\|(5) for examples of \fInnrpd\fR\|(8) authentication configuration
261 that uses \fBckpasswd\fR to check passwords.
262 .PP
263 An example \s-1PAM\s0 configuration for \fI/etc/pam.conf\fR that tells \fBckpasswd\fR
264 to check usernames and passwords against system accounts is:
265 .PP
266 .Vb 2
267 \&    nnrpd auth    required pam_unix.so
268 \&    nnrpd account required pam_unix.so
269 .Ve
270 .PP
271 Your system may want you to instead create a file named \fInnrpd\fR in
272 \&\fI/etc/pam.d\fR with lines like:
273 .PP
274 .Vb 2
275 \&    auth    required pam_unix.so
276 \&    account required pam_unix.so
277 .Ve
278 .PP
279 This is only the simplest configuration.  You may be able to include
280 common shared files, and you may want to stack other modules, either to
281 allow different authentication methods or to apply restrictions like lists
282 of users who can't authenticate using \fBckpasswd\fR.  The best guide is the
283 documentation for your system and the other \s-1PAM\s0 configurations you're
284 already using.
285 .PP
286 To test to make sure that \fBckpasswd\fR is working correctly, you can run it
287 manually and then give it the username (prefixed with \f(CW\*(C`ClientAuthname:\*(C'\fR)
288 and password (prefixed with \f(CW\*(C`ClientPassword:\*(C'\fR) on standard input.  For
289 example:
290 .PP
291 .Vb 2
292 \&    (echo 'ClientAuthname: test' ; echo 'ClientPassword: testing') \e
293 \&        | ckpasswd \-f /path/to/passwd/file
294 .Ve
295 .PP
296 will check a username of \f(CW\*(C`test\*(C'\fR and a password of \f(CW\*(C`testing\*(C'\fR against the
297 username and passwords stored in \fI/path/to/passwd/file\fR.  On success,
298 \&\fBckpasswd\fR will print \f(CW\*(C`User:test\*(C'\fR and exit with status 0.  On failure,
299 it will print some sort of error message and exit a non-zero status.
300 .SH "HISTORY"
301 .IX Header "HISTORY"
302 Written by Russ Allbery <rra@stanford.edu> for InterNetNews.
303 .PP
304 $Id: ckpasswd.8 7880 2008-06-16 20:37:13Z iulius $
305 .SH "SEE ALSO"
306 .IX Header "SEE ALSO"
307 \&\fIreaders.conf\fR\|(5), \fInnrpd\fR\|(8)
308 .PP
309 Linux users who want to use \s-1PAM\s0 should read the Linux-PAM System
310 Administrator's Guide at
311 <http://www.kernel.org/pub/linux/libs/pam/Linux\-PAM\-html/Linux\-PAM_SAG.html>.