2 .\" <!-- Copyright 1998 - 2007 Double Precision, Inc. See COPYING for -->
3 .\" <!-- distribution information. -->
5 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
6 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
8 .\" Manual: Double Precision, Inc.
9 .\" Source: Double Precision, Inc.
12 .TH "MAKEUSERDB" "8" "09/08/2017" "Double Precision, Inc." "Double Precision, Inc."
13 .\" -----------------------------------------------------------------
14 .\" * Define some portability stuff
15 .\" -----------------------------------------------------------------
16 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
17 .\" http://bugs.debian.org/507673
18 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
19 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22 .\" -----------------------------------------------------------------
23 .\" * set default formatting
24 .\" -----------------------------------------------------------------
25 .\" disable hyphenation
27 .\" disable justification (adjust text to left margin only)
29 .\" -----------------------------------------------------------------
30 .\" * MAIN CONTENT STARTS HERE *
31 .\" -----------------------------------------------------------------
33 makeuserdb \- create @userdb@
35 .HP \w'\fBmakeuserdb\fR\ 'u
36 \fBmakeuserdb\fR [\-f\ \fIfilename\fR]
37 .HP \w'\fBpw2userdb\fR\ 'u
39 .HP \w'\fBvchkpw2userdb\fR\ 'u
40 \fBvchkpw2userdb\fR [\-\-vpopmailhome=\fIdir\fR] [\-\-todir=\fIdir\fR]
48 @userdb@\*(Aqs contents are described later in this document\&.
50 Courier, and other applications use
52 as a substitute/complement for your system password file\&. The usual purpose for
54 is to specify "virtual" accounts \- accounts that do not have an associated system login\&. Usually (but not necessarily) all virtual accounts share the same system userid\&.
56 may also replace your system password file\&. Because the system password file is a text file, when there\*(Aqs a large number of accounts it will be significantly faster to search
57 @userdb\&.dat@, which is a binary database, instead of a flat text file that the system password file usually is\&.
61 command can be safely executed during normal system activity\&.
68 \fIfilename\fR, instead of the default
72 .SS "Format of @userdb@"
75 is a plain text file that can be created using any text editor\&. Blank lines are ignored\&. Lines that start with the # character are comments, and are also ignored\&. Other lines define properties of a single "account", one line per account\&.
77 may be a directory instead of a plain file\&. In that case all files in
79 are essentially concatenated, and are treated as a single file\&. Each line takes the following format:
85 \fIname\fR<TAB>\fIfield\fR=\fIvalue\fR|\fIfield\fR=\fIvalue\fR\&.\&.\&.
92 is the account name\&.
94 MUST contain only lowercase characters If
96 is configured to treat lowercase and uppercase account names as identical,
98 is followed by exactly one tab character, then a list of field/value pairs separated by vertical slashes\&.
100 is the name of the field,
102 is the field value\&. Fields and values themself cannot contain slashes or control characters\&. Fields may be specified in any order\&. Here are all the currently defined fields\&. Note that not every field is used by every application that reads
108 is a (possibly) unique numerical user ID for this account\&.
113 is a (possibly) unique numerical group ID for this account\&.
118 is the account\*(Aqs home directory\&.
123 is the account\*(Aqs default login shell\&.
128 is the account\*(Aqs password\&. See
129 \m[blue]\fB\fBuserdbpw\fR(8)\fR\m[]\&\s-2\u[1]\d\s+2
130 for details on how to set up this field\&.
132 \fIpop3pw, esmtppw, imappw\&.\&.\&.\fR
135 specifies a separate password used only for authenticating access using a specific service, such as POP3, IMAP, or anything else\&. If not defined,
137 is always used\&. This allows access to an account to be restricted only to certain services, such as POP3, even if other services are also enabled on the server\&.
142 specifies the location of the account\*(Aqs Maildir mailbox\&. This is an optional field that is normally used when
144 is used to provide aliases for other mail accounts\&. For example, one particular multi\-domain E\-mail service configuration that\*(Aqs used by both
148 servers is to deliver mail for a mailbox in a virtual domain, such as "user@example\&.com", to a local mailbox called "example\-user"\&. Instead of requiring the E\-mail account holder to log in as "example\-user" to download mail from this account, a
150 entry for "user@example\&.com" is set up with
152 set to the location of example\-user\*(Aqs Maildir mailbox, thus hiding the internal mail configuration from the E\-mail account holder\*(Aqs view\&.
157 specifies the maildir quota for the account\*(Aqs Maildir\&. This has nothing to do with actual filesystem quotas\&.
159 has a software\-based Maildir quota enforcement mechanism which requires additional setup and configuration\&. See
160 \m[blue]\fB\fBmaildirquota\fR(7)\fR\m[]\&\s-2\u[2]\d\s+2
161 for additional information\&.
162 .SS "@userdb@shadow\&.dat"
164 All fields whose name ends with \*(Aqpw\*(Aq will NOT copied to
165 @userdb@\&.dat\&. These fields will be copied to
166 @userdb@shadow\&.dat\&.
170 without any group and world permissions\&. Note that
174 has any group or world permissions\&.
175 .SS "CONVERTING /etc/passwd and vpopmail to @userdb@ format"
182 files and converts all entries to the
184 format, printing the result on standard output\&. The output of
188 (or as some file in this subdirectory)\&. Linear searches of
190 can be very slow when you have tens of thousands of accounts\&. Programs like
194 first\&. By saving the system password file in
196 it is possible to significantly reduce the amount of time it takes to look up this information\&.
198 After saving the output of
199 \fBpw2userdb\fR, you must still run
205 converts a vpopmail\-style directory hierarchy to the
207 format\&. This is an external virtual domain management package that\*(Aqs often used with
211 Generally, an account named \*(Aqvpopmail\*(Aq is reserved for this purpose\&. In that account the file
213 has the same layout as
214 /etc/passwd, and performs a similar function, except that all userid in
216 have the same userid\&. Additionally, the
218 subdirectory stores virtual accounts for multiple domains\&. For example,
219 domains/example\&.com/vpasswd
220 has the passwd file for the domain
221 \fIexample\&.com\fR\&. Some systems also have a soft link,
222 \fIdomains/default\fR, that points to a domain that\*(Aqs considered a "default" domain\&.
226 reads all this information, and tries to convert it into the
229 \fI\-\-vpopmailhost\fR
230 option specifies the top level directory, if it is not the home directory of the vpopmail account\&.
234 script prints the results on standard output\&. If specified, the
236 option tries to convert all
238 files one at a time, saving each one individually in
239 \fIdir\fR\&. For example:
246 vchkpw2userdb \-\-todir=@userdb@/vpopmail
253 It is still necessary to run
254 \fBmakeuserdb\fR, of course, to create the binary database file
257 NOTE: You are still required to create the
259 entry which maps system userids back to accounts, "\fIuid\fR=<TAB>\fIname\fR", if that\*(Aqs applicable\&.
261 will not do it for you\&.
265 may complain about duplicate entries, if your "default" entries in
268 domains/default/vpasswd
269 are the same as anything in any other
271 file\&. It is also likely that you\*(Aqll end up with duplicate, but distinct, entries for every account in the default domain\&. For example, if your default domain is example\&.com, you\*(Aqll end up with duplicate entries \- you\*(Aqll have entries for both
274 \fIuser@example\&.com\fR\&.
276 If you intend to maintain the master set of accounts using vchkpw/vpopmail, in order to avoid cleaning this up every time, you might want to consider doing the following: run
280 option\&. Then, go into the resulting directory, and replace one of the redundant files with a soft link to
281 /dev/null\&. This allows you to run
283 without having to go in and cleaning up again, afterwards\&.
293 @tmpdir@/userdb\&.tmp \- temporary file
294 @tmpdir@/userdbshadow\&.tmp \- temporary file
302 is a Perl script, and uses Perl\*(Aqs portable locking\&. Perl\*(Aqs documentation notes that certain combinations of locking options may not work with some networks\&.
305 \m[blue]\fB\fBuserdb\fR(8)\fR\m[]\&\s-2\u[3]\d\s+2,
306 \m[blue]\fB\fBmaildrop\fR(8)\fR\m[]\&\s-2\u[4]\d\s+2,
307 \m[blue]\fB\fBcourier\fR(8)\fR\m[]\&\s-2\u[5]\d\s+2,
308 \m[blue]\fB\fBmaildirquota\fR(7)\fR\m[]\&\s-2\u[2]\d\s+2\&.
313 \%[set $man.base.url.for.relative.links]/userdbpw.html
316 \fBmaildirquota\fR(7)
318 \%[set $man.base.url.for.relative.links]/maildirquota.html
323 \%[set $man.base.url.for.relative.links]/userdb.html
328 \%[set $man.base.url.for.relative.links]/maildrop.html
333 \%[set $man.base.url.for.relative.links]/courier.html