1 .\" <!-- $Id: makeuserdb.sgml,v 1.8 2008/07/13 21:58:26 mrsam Exp $ -->
2 .\" <!-- Copyright 1998 - 2007 Double Precision, Inc. See COPYING for -->
3 .\" <!-- distribution information. -->
6 .\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
8 .\" Manual: Double Precision, Inc.
9 .\" Source: Double Precision, Inc.
11 .TH "MAKEUSERDB" "8" "08/23/2008" "Double Precision, Inc." "Double Precision, Inc."
12 .\" disable hyphenation
14 .\" disable justification (adjust text to left margin only)
17 makeuserdb - create @userdb@
20 \fBmakeuserdb\fR [\-f\ \fIfilename\fR]
24 \fBvchkpw2userdb\fR [\-\-vpopmailhome=\fIdir\fR] [\-\-todir=\fIdir\fR]
33 \fI@userdb@\fR\'s contents are described later in this document\.
35 Courier, and other applications use
37 as a substitute/complement for your system password file\. The usual purpose for
39 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\.
41 may also replace your system password file\. Because the system password file is a text file, when there\'s a large number of accounts it will be significantly faster to search
42 \fI@userdb\.dat@\fR, which is a binary database, instead of a flat text file that the system password file usually is\.
46 command can be safely executed during normal system activity\.
51 \fI\fIfilename\fR\fR\fI\.dat\fR
53 \fI\fIfilename\fR\fR, instead of the default
57 .SS "Format of \fI@userdb@\fR"
61 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\.
63 may be a directory instead of a plain file\. In that case all files in
65 are essentially concatenated, and are treated as a single file\. Each line takes the following format:
69 \fIname\fR<TAB>\fIfield\fR=\fIvalue\fR|\fIfield\fR=\fIvalue\fR\.\.\.
76 MUST contain only lowercase characters If
78 is configured to treat lowercase and uppercase account names as identical,
80 is followed by exactly one tab character, then a list of field/value pairs separated by vertical slashes\.
82 is the name of the field,
84 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
91 is a (possibly) unique numerical user ID for this account\.
97 is a (possibly) unique numerical group ID for this account\.
103 is the account\'s home directory\.
109 is the account\'s default login shell\.
115 is the account\'s password\. See
116 \fI\fBuserdbpw\fR(8)\fR\&[1]
117 for details on how to set up this field\.
120 \fIpop3pw, esmtppw, imappw\.\.\.\fR
123 specifies a separate password used only for authenticating access using a specific service, such as POP3, IMAP, or anything else\. If not defined,
125 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\.
131 specifies the location of the account\'s Maildir mailbox\. This is an optional field that is normally used when
133 is used to provide aliases for other mail accounts\. For example, one particular multi\-domain E\-mail service configuration that\'s used by both
137 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
139 entry for "user@example\.com" is set up with
141 set to the location of example\-user\'s Maildir mailbox, thus hiding the internal mail configuration from the E\-mail account holder\'s view\.
147 specifies the maildir quota for the account\'s Maildir\. This has nothing to do with actual filesystem quotas\.
149 has a software\-based Maildir quota enforcement mechanism which requires additional setup and configuration\. See
150 \fI\fBmaildirquota\fR(7)\fR\&[2]
151 for additional information\.
152 .SS "\fI@userdb@shadow\.dat\fR"
154 All fields whose name ends with \'pw\' will NOT copied to
155 \fI@userdb@\.dat\fR\. These fields will be copied to
156 \fI@userdb@shadow\.dat\fR\.
159 \fI@userdb@shadow\.dat\fR
160 without any group and world permissions\. Note that
164 has any group or world permissions\.
165 .SS "CONVERTING \fI/etc/passwd\fR and vpopmail to \fI@userdb@\fR format"
173 files and converts all entries to the
175 format, printing the result on standard output\. The output of
179 (or as some file in this subdirectory)\. Linear searches of
181 can be very slow when you have tens of thousands of accounts\. Programs like
185 first\. By saving the system password file in
187 it is possible to significantly reduce the amount of time it takes to look up this information\.
189 After saving the output of
190 \fBpw2userdb\fR, you must still run
193 \fI@userdb@\.dat\fR\.
197 converts a vpopmail\-style directory hierarchy to the
199 format\. This is an external virtual domain management package that\'s often used with
203 Generally, an account named \'vpopmail\' is reserved for this purpose\. In that account the file
205 has the same layout as
206 \fI/etc/passwd\fR, and performs a similar function, except that all userid in
208 have the same userid\. Additionally, the
210 subdirectory stores virtual accounts for multiple domains\. For example,
211 \fIdomains/example\.com/vpasswd\fR
212 has the passwd file for the domain
213 \fIexample\.com\fR\. Some systems also have a soft link,
214 \fIdomains/default\fR, that points to a domain that\'s considered a "default" domain\.
218 reads all this information, and tries to convert it into the
221 \fI\-\-vpopmailhost\fR
222 option specifies the top level directory, if it is not the home directory of the vpopmail account\.
226 script prints the results on standard output\. If specified, the
228 option tries to convert all
230 files one at a time, saving each one individually in
231 \fIdir\fR\. For example:
236 vchkpw2userdb \-\-todir=@userdb@/vpopmail
241 It is still necessary to run
242 \fBmakeuserdb\fR, of course, to create the binary database file
245 NOTE: You are still required to create the
247 entry which maps system userids back to accounts, "\fIuid\fR=<TAB>\fIname\fR", if that\'s applicable\.
249 will not do it for you\.
253 may complain about duplicate entries, if your "default" entries in
256 \fIdomains/default/vpasswd\fR
257 are the same as anything in any other
259 file\. It is also likely that you\'ll end up with duplicate, but distinct, entries for every account in the default domain\. For example, if your default domain is example\.com, you\'ll end up with duplicate entries \- you\'ll have entries for both
262 \fIuser@example\.com\fR\.
264 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
268 option\. Then, go into the resulting directory, and replace one of the redundant files with a soft link to
269 \fI/dev/null\fR\. This allows you to run
271 without having to go in and cleaning up again, afterwards\.
278 \fI@userdb@shadow\.dat\fR
279 \fI@tmpdir@/userdb\.tmp\fR \- temporary file
280 \fI@tmpdir@/userdbshadow\.tmp\fR \- temporary file
286 is a Perl script, and uses Perl\'s portable locking\. Perl\'s documentation notes that certain combinations of locking options may not work with some networks\.
290 \fI\fBuserdb\fR(8)\fR\&[3],
291 \fI\fBmaildrop\fR(8)\fR\&[4],
292 \fI\fBcourier\fR(8)\fR\&[5],
293 \fI\fBmaildirquota\fR(7)\fR\&[2]\.
301 \fBmaildirquota\fR(7)
HCoop / hcoop / debian / courier-authlib.git / blob