* Add this nice filesystem testing tool that I've recently
[dragonfly.git] / contrib / libpam / doc / modules / pam_userdb.sgml
1 <!--
2    This file was written by Cristian Gafton <gafton@redhat.com>
3 -->
4
5 <sect1>The userdb module
6
7 <sect2>Synopsis
8
9 <p>
10 <descrip>
11
12 <tag><bf>Module Name:</bf></tag>
13 <tt/pam_userdb/
14
15 <tag><bf>Author:</bf></tag>
16 Cristian Gafton &lt;gafton@redhat.com&gt;
17
18 <tag><bf>Maintainer:</bf></tag>
19 Author.
20
21 <tag><bf>Management groups provided:</bf></tag>
22 authentication
23
24 <tag><bf>Cryptographically sensitive:</bf></tag>
25         
26 <tag><bf>Security rating:</bf></tag>
27
28 <tag><bf>Clean code base:</bf></tag>
29
30 <tag><bf>System dependencies:</bf></tag>
31 Requires Berkeley DB.
32
33 <tag><bf>Network aware:</bf></tag>
34
35 </descrip>
36
37 <sect2>Overview of module
38
39 <p>
40 Look up users in a .db database and verify their password against
41 what is contained in that database.
42
43 <sect2>Authentication component
44
45 <p>
46 <descrip>
47
48 <tag><bf>Recognized arguments:</bf></tag>
49 <tt/debug/;
50 <tt/icase/;
51 <tt/dump/;
52 <tt/db=XXXX/;
53
54 <tag><bf>Description:</bf></tag>
55
56 This module is used to verify a username/password pair against values stored in
57 a Berkeley DB database. The database is indexed by the username, and the data 
58 fields corresponding to the username keys are the passwords, in unencrypted form,
59 so caution must be exercised over the access rights to the DB database itself..
60
61 The module will read the password from the user using the conversation mechanism. If
62 you are using this module on top of another authetication module (like <tt/pam_pwdb/;)
63 then you should tell that module to read the entered password from the PAM_AUTHTOK field, which is set by this module.
64
65 <p>
66 The action of the module may be modified from this default by one or
67 more of the following flags in the <tt>/etc/pam.d/&lt;service&gt;</tt> file.
68 <itemize>
69 <item>
70 <tt/debug/ -
71 Supply more debugging information to <tt/syslog(3)/.
72
73 <item>
74 <tt/icase/ -
75 Perform the password comparisons case insensitive.
76
77 <item>
78 <tt/dump/ -
79 dump all the entries in the database to the log (eek,
80 don't do this by default!)
81
82 <item>
83 <tt/db=XXXX/ - 
84 use the database found on pathname XXXX. Note that Berkeley DB usually adds the 
85 needed filename extension for you, so you should use something like <tt>/etc/foodata</tt>
86 instead of <tt>/etc/foodata.db</tt>.
87
88 </itemize>
89
90 <tag><bf>Examples/suggested usage:</bf></tag>
91
92 This is a normal ftp configuration file (usually placed as <tt>/etc/pam.d/ftp</tt> 
93 on most systems) that will accept for login users whose username/password pairs are 
94 provided in the <tt>/tmp/dbtest.db</tt> file:
95
96 <tscreen>
97 <verb>
98 #%PAM-1.0
99 auth       required     pam_listfile.so item=user sense=deny file=/etc/ftpusers onerr=succeed
100 auth       sufficient   pam_userdb.so icase db=/tmp/dbtest
101 auth       required     pam_pwdb.so shadow nullok try_first_pass
102 auth       required     pam_shells.so
103 account    required     pam_pwdb.so
104 session    required     pam_pwdb.so
105 </verb>
106 </tscreen>
107
108 </descrip>
109
110 <!--
111 End of sgml insert for this module.
112 -->