Commit | Line | Data |
---|---|---|
b0322a85 | 1 | '\" t |
d9898ee8 | 2 | .\" <!-- Copyright 1998 - 2007 Double Precision, Inc. See COPYING for --> |
3 | .\" <!-- distribution information. --> | |
4 | .\" Title: makeuserdb | |
0e333c05 CE |
5 | .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] |
6 | .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> | |
7 | .\" Date: 09/08/2017 | |
d9898ee8 | 8 | .\" Manual: Double Precision, Inc. |
9 | .\" Source: Double Precision, Inc. | |
b0322a85 | 10 | .\" Language: English |
d9898ee8 | 11 | .\" |
0e333c05 | 12 | .TH "MAKEUSERDB" "8" "09/08/2017" "Double Precision, Inc." "Double Precision, Inc." |
b0322a85 CE |
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 | .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
20 | .ie \n(.g .ds Aq \(aq | |
21 | .el .ds Aq ' | |
22 | .\" ----------------------------------------------------------------- | |
23 | .\" * set default formatting | |
24 | .\" ----------------------------------------------------------------- | |
d9898ee8 | 25 | .\" disable hyphenation |
26 | .nh | |
27 | .\" disable justification (adjust text to left margin only) | |
28 | .ad l | |
b0322a85 CE |
29 | .\" ----------------------------------------------------------------- |
30 | .\" * MAIN CONTENT STARTS HERE * | |
31 | .\" ----------------------------------------------------------------- | |
d9898ee8 | 32 | .SH "NAME" |
b0322a85 | 33 | makeuserdb \- create @userdb@ |
d9898ee8 | 34 | .SH "SYNOPSIS" |
b0322a85 | 35 | .HP \w'\fBmakeuserdb\fR\ 'u |
d9898ee8 | 36 | \fBmakeuserdb\fR [\-f\ \fIfilename\fR] |
b0322a85 | 37 | .HP \w'\fBpw2userdb\fR\ 'u |
d9898ee8 | 38 | \fBpw2userdb\fR |
b0322a85 | 39 | .HP \w'\fBvchkpw2userdb\fR\ 'u |
d9898ee8 | 40 | \fBvchkpw2userdb\fR [\-\-vpopmailhome=\fIdir\fR] [\-\-todir=\fIdir\fR] |
41 | .SH "DESCRIPTION" | |
42 | .PP | |
d9898ee8 | 43 | \fBmakeuserdb\fR |
44 | creates | |
b0322a85 | 45 | @userdb@\&.dat |
d9898ee8 | 46 | from the contents of |
b0322a85 CE |
47 | @userdb@\&. |
48 | @userdb@\*(Aqs contents are described later in this document\&. | |
d9898ee8 | 49 | Maildrop, |
50 | Courier, and other applications use | |
b0322a85 CE |
51 | @userdb@\&.dat |
52 | as a substitute/complement for your system password file\&. The usual purpose for | |
53 | @userdb@\&.dat | |
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\&. | |
55 | @userdb@\&.dat | |
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\&. | |
d9898ee8 | 58 | .PP |
59 | The | |
60 | \fBmakeuserdb\fR | |
b0322a85 | 61 | command can be safely executed during normal system activity\&. |
d9898ee8 | 62 | .PP |
63 | The | |
64 | \fB\-f\fR | |
65 | option creates | |
b0322a85 | 66 | \fIfilename\fR\&.dat |
d9898ee8 | 67 | from |
b0322a85 CE |
68 | \fIfilename\fR, instead of the default |
69 | @userdb@\&.dat | |
d9898ee8 | 70 | from |
b0322a85 CE |
71 | @userdb@\&. |
72 | .SS "Format of @userdb@" | |
d9898ee8 | 73 | .PP |
b0322a85 CE |
74 | @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\&. | |
76 | @userdb@ | |
77 | may be a directory instead of a plain file\&. In that case all files in | |
78 | @userdb@ | |
79 | are essentially concatenated, and are treated as a single file\&. Each line takes the following format: | |
d9898ee8 | 80 | .sp |
b0322a85 | 81 | .if n \{\ |
d9898ee8 | 82 | .RS 4 |
b0322a85 | 83 | .\} |
d9898ee8 | 84 | .nf |
b0322a85 | 85 | \fIname\fR<TAB>\fIfield\fR=\fIvalue\fR|\fIfield\fR=\fIvalue\fR\&.\&.\&. |
d9898ee8 | 86 | .fi |
b0322a85 | 87 | .if n \{\ |
d9898ee8 | 88 | .RE |
b0322a85 | 89 | .\} |
d9898ee8 | 90 | .PP |
91 | \fIname\fR | |
b0322a85 | 92 | is the account name\&. |
d9898ee8 | 93 | \fIname\fR |
94 | MUST contain only lowercase characters If | |
95 | Courier | |
96 | is configured to treat lowercase and uppercase account names as identical, | |
97 | \fIname\fR | |
b0322a85 | 98 | is followed by exactly one tab character, then a list of field/value pairs separated by vertical slashes\&. |
d9898ee8 | 99 | \fIfield\fR |
100 | is the name of the field, | |
101 | \fIvalue\fR | |
b0322a85 CE |
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 |
103 | @userdb@\&.dat\&. | |
d9898ee8 | 104 | .PP |
d9898ee8 | 105 | \fIuid\fR |
106 | \- | |
107 | \fIvalue\fR | |
b0322a85 | 108 | is a (possibly) unique numerical user ID for this account\&. |
d9898ee8 | 109 | .PP |
d9898ee8 | 110 | \fIgid\fR |
111 | \- | |
112 | \fIvalue\fR | |
b0322a85 | 113 | is a (possibly) unique numerical group ID for this account\&. |
d9898ee8 | 114 | .PP |
d9898ee8 | 115 | \fIhome\fR |
116 | \- | |
117 | \fIvalue\fR | |
b0322a85 | 118 | is the account\*(Aqs home directory\&. |
d9898ee8 | 119 | .PP |
d9898ee8 | 120 | \fIshell\fR |
121 | \- | |
122 | \fIvalue\fR | |
b0322a85 | 123 | is the account\*(Aqs default login shell\&. |
d9898ee8 | 124 | .PP |
d9898ee8 | 125 | \fIsystempw\fR |
126 | \- | |
127 | \fIvalue\fR | |
b0322a85 CE |
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\&. | |
d9898ee8 | 131 | .PP |
b0322a85 | 132 | \fIpop3pw, esmtppw, imappw\&.\&.\&.\fR |
d9898ee8 | 133 | \- |
134 | \fIvalue\fR | |
b0322a85 | 135 | specifies a separate password used only for authenticating access using a specific service, such as POP3, IMAP, or anything else\&. If not defined, |
d9898ee8 | 136 | \fIsystempw\fR |
b0322a85 | 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\&. |
d9898ee8 | 138 | .PP |
d9898ee8 | 139 | \fImail\fR |
140 | \- | |
141 | \fIvalue\fR | |
b0322a85 | 142 | specifies the location of the account\*(Aqs Maildir mailbox\&. This is an optional field that is normally used when |
d9898ee8 | 143 | \fBuserdb\fR |
b0322a85 | 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 |
d9898ee8 | 145 | Qmail |
146 | and | |
147 | Courier | |
b0322a85 | 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 |
d9898ee8 | 149 | \fBuserdb\fR |
b0322a85 | 150 | entry for "user@example\&.com" is set up with |
d9898ee8 | 151 | \fImail\fR |
b0322a85 | 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\&. |
d9898ee8 | 153 | .PP |
d9898ee8 | 154 | \fIquota\fR |
155 | \- | |
156 | \fIvalue\fR | |
b0322a85 | 157 | specifies the maildir quota for the account\*(Aqs Maildir\&. This has nothing to do with actual filesystem quotas\&. |
d9898ee8 | 158 | Courier |
b0322a85 CE |
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" | |
d9898ee8 | 163 | .PP |
b0322a85 CE |
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\&. | |
d9898ee8 | 167 | \fBmakeuserdb\fR |
168 | creates | |
b0322a85 CE |
169 | @userdb@shadow\&.dat |
170 | without any group and world permissions\&. Note that | |
d9898ee8 | 171 | \fBmakeuserdb\fR |
172 | reports an error if | |
173 | \fB@userdb@\fR | |
b0322a85 CE |
174 | has any group or world permissions\&. |
175 | .SS "CONVERTING /etc/passwd and vpopmail to @userdb@ format" | |
d9898ee8 | 176 | .PP |
d9898ee8 | 177 | \fBpw2userdb\fR |
178 | reads the | |
b0322a85 | 179 | /etc/passwd |
d9898ee8 | 180 | and |
b0322a85 | 181 | /etc/shadow |
d9898ee8 | 182 | files and converts all entries to the |
b0322a85 CE |
183 | @userdb@ |
184 | format, printing the result on standard output\&. The output of | |
d9898ee8 | 185 | \fBpw2userdb\fR |
186 | can be saved as | |
187 | \fB@userdb@\fR | |
b0322a85 CE |
188 | (or as some file in this subdirectory)\&. Linear searches of |
189 | /etc/passwd | |
190 | can be very slow when you have tens of thousands of accounts\&. Programs like | |
d9898ee8 | 191 | \fBmaildrop\fR |
192 | always look in | |
b0322a85 CE |
193 | @userdb@ |
194 | first\&. By saving the system password file in | |
195 | @userdb@ | |
196 | it is possible to significantly reduce the amount of time it takes to look up this information\&. | |
d9898ee8 | 197 | .PP |
198 | After saving the output of | |
199 | \fBpw2userdb\fR, you must still run | |
200 | \fBmakeuserdb\fR | |
201 | to create | |
b0322a85 | 202 | @userdb@\&.dat\&. |
d9898ee8 | 203 | .PP |
d9898ee8 | 204 | \fBvchkpw2userdb\fR |
205 | converts a vpopmail\-style directory hierarchy to the | |
b0322a85 CE |
206 | @userdb@ |
207 | format\&. This is an external virtual domain management package that\*(Aqs often used with | |
d9898ee8 | 208 | Qmail |
b0322a85 | 209 | servers\&. |
d9898ee8 | 210 | .PP |
b0322a85 CE |
211 | Generally, an account named \*(Aqvpopmail\*(Aq is reserved for this purpose\&. In that account the file |
212 | users/vpasswd | |
d9898ee8 | 213 | has the same layout as |
b0322a85 CE |
214 | /etc/passwd, and performs a similar function, except that all userid in |
215 | users/vpasswd | |
216 | have the same userid\&. Additionally, the | |
217 | domains | |
218 | subdirectory stores virtual accounts for multiple domains\&. For example, | |
219 | domains/example\&.com/vpasswd | |
d9898ee8 | 220 | has the passwd file for the domain |
b0322a85 CE |
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\&. | |
d9898ee8 | 223 | .PP |
224 | The | |
225 | \fBvchkpw2userdb\fR | |
226 | reads all this information, and tries to convert it into the | |
b0322a85 CE |
227 | @userdb@ |
228 | format\&. The | |
d9898ee8 | 229 | \fI\-\-vpopmailhost\fR |
b0322a85 | 230 | option specifies the top level directory, if it is not the home directory of the vpopmail account\&. |
d9898ee8 | 231 | .PP |
232 | The | |
233 | \fBvchkpw2userdb\fR | |
b0322a85 | 234 | script prints the results on standard output\&. If specified, the |
d9898ee8 | 235 | \fI\-\-todir\fR |
236 | option tries to convert all | |
b0322a85 | 237 | vpasswd |
d9898ee8 | 238 | files one at a time, saving each one individually in |
b0322a85 | 239 | \fIdir\fR\&. For example: |
d9898ee8 | 240 | .sp |
b0322a85 | 241 | .if n \{\ |
d9898ee8 | 242 | .RS 4 |
b0322a85 | 243 | .\} |
d9898ee8 | 244 | .nf |
245 | mkdir @userdb@ | |
246 | vchkpw2userdb \-\-todir=@userdb@/vpopmail | |
247 | makeuserdb | |
248 | .fi | |
b0322a85 | 249 | .if n \{\ |
d9898ee8 | 250 | .RE |
b0322a85 | 251 | .\} |
d9898ee8 | 252 | .PP |
253 | It is still necessary to run | |
254 | \fBmakeuserdb\fR, of course, to create the binary database file | |
b0322a85 | 255 | @userdb@\&.dat |
d9898ee8 | 256 | .PP |
257 | NOTE: You are still required to create the | |
258 | \fB@userdb@\fR | |
b0322a85 | 259 | entry which maps system userids back to accounts, "\fIuid\fR=<TAB>\fIname\fR", if that\*(Aqs applicable\&. |
d9898ee8 | 260 | \fBvchkpw2userdb\fR |
b0322a85 | 261 | will not do it for you\&. |
d9898ee8 | 262 | .PP |
263 | NOTE: | |
264 | \fBmakeuserdb\fR | |
265 | may complain about duplicate entries, if your "default" entries in | |
b0322a85 | 266 | users/vpasswd |
d9898ee8 | 267 | or |
b0322a85 | 268 | domains/default/vpasswd |
d9898ee8 | 269 | are the same as anything in any other |
b0322a85 CE |
270 | @userdb@ |
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 | |
d9898ee8 | 272 | \fIuser\fR |
273 | and | |
b0322a85 | 274 | \fIuser@example\&.com\fR\&. |
d9898ee8 | 275 | .PP |
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 | |
277 | \fBvchkpw2userdb\fR | |
278 | once, using the | |
279 | \fI\-\-todir\fR | |
b0322a85 CE |
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 | |
d9898ee8 | 282 | \fBvchkpw2userdb\fR |
b0322a85 | 283 | without having to go in and cleaning up again, afterwards\&. |
d9898ee8 | 284 | .SH "FILES" |
285 | .sp | |
b0322a85 | 286 | .if n \{\ |
d9898ee8 | 287 | .RS 4 |
b0322a85 | 288 | .\} |
d9898ee8 | 289 | .nf |
b0322a85 CE |
290 | @userdb@ |
291 | @userdb@\&.dat | |
292 | @userdb@shadow\&.dat | |
293 | @tmpdir@/userdb\&.tmp \- temporary file | |
294 | @tmpdir@/userdbshadow\&.tmp \- temporary file | |
d9898ee8 | 295 | .fi |
b0322a85 | 296 | .if n \{\ |
d9898ee8 | 297 | .RE |
b0322a85 | 298 | .\} |
d9898ee8 | 299 | .SH "BUGS" |
300 | .PP | |
301 | \fBmakeuserdb\fR | |
b0322a85 | 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\&. |
d9898ee8 | 303 | .SH "SEE ALSO" |
304 | .PP | |
b0322a85 CE |
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\&. | |
8d138742 | 309 | .SH "NOTES" |
d9898ee8 | 310 | .IP " 1." 4 |
311 | \fBuserdbpw\fR(8) | |
312 | .RS 4 | |
b0322a85 | 313 | \%[set $man.base.url.for.relative.links]/userdbpw.html |
d9898ee8 | 314 | .RE |
315 | .IP " 2." 4 | |
316 | \fBmaildirquota\fR(7) | |
317 | .RS 4 | |
b0322a85 | 318 | \%[set $man.base.url.for.relative.links]/maildirquota.html |
d9898ee8 | 319 | .RE |
320 | .IP " 3." 4 | |
321 | \fBuserdb\fR(8) | |
322 | .RS 4 | |
b0322a85 | 323 | \%[set $man.base.url.for.relative.links]/userdb.html |
d9898ee8 | 324 | .RE |
325 | .IP " 4." 4 | |
326 | \fBmaildrop\fR(8) | |
327 | .RS 4 | |
b0322a85 | 328 | \%[set $man.base.url.for.relative.links]/maildrop.html |
d9898ee8 | 329 | .RE |
330 | .IP " 5." 4 | |
331 | \fBcourier\fR(8) | |
332 | .RS 4 | |
b0322a85 | 333 | \%[set $man.base.url.for.relative.links]/courier.html |
d9898ee8 | 334 | .RE |