|
1 |
|
2 Vmailmgr Configuration Files |
|
3 |
|
4 14 September 2000 |
|
5 |
|
6 |
|
7 Bruce Guenter |
|
8 _________________________________________________________________ |
|
9 |
|
10 Table of Contents |
|
11 |
|
12 * 1. General Information |
|
13 + 1.1 Search Order |
|
14 + 1.2 File Types |
|
15 + 1.3 Command Execution |
|
16 * 2. Configuration Files |
|
17 + 2.1 authvmailmgr-error |
|
18 + 2.2 authvmailmgr-loginfail |
|
19 + 2.3 authvmailmgr-postsetuid |
|
20 + 2.4 authvmailmgr-presetuid |
|
21 + 2.5 autoresponse-dir |
|
22 + 2.6 autoresponse-file |
|
23 + 2.7 bulletin-dir |
|
24 + 2.8 checkvpw-error |
|
25 + 2.9 checkvpw-loginfail |
|
26 + 2.10 checkvpw-postexec |
|
27 + 2.11 checkvpw-postsetuid |
|
28 + 2.12 checkvpw-presetuid |
|
29 + 2.13 default-expiry |
|
30 + 2.14 default-maildir |
|
31 + 2.15 default-msgcount |
|
32 + 2.16 default-msgsize |
|
33 + 2.17 default-hardquota |
|
34 + 2.18 default-softquota |
|
35 + 2.19 default-username |
|
36 + 2.20 error-maildir |
|
37 + 2.21 global-bulletin-dir |
|
38 + 2.22 maildir-arg-str |
|
39 + 2.23 password-file |
|
40 + 2.24 postmaster-aliases |
|
41 + 2.25 postmaster-email |
|
42 + 2.26 qmail-root |
|
43 + 2.27 separators |
|
44 + 2.28 socket-file |
|
45 + 2.29 user-dir |
|
46 + 2.30 user-dir-bits |
|
47 + 2.31 user-dir-slices |
|
48 + 2.32 vdeliver-postdeliver |
|
49 + 2.33 vdeliver-predeliver |
|
50 + 2.34 vsetup-pre |
|
51 + 2.35 vsetup-pre |
|
52 _________________________________________________________________ |
|
53 |
|
54 1. General Information |
|
55 |
|
56 1.1 Search Order |
|
57 |
|
58 The system will look for the configuration files listed below in one |
|
59 of the following three locations, in the order they are listed: |
|
60 1. The domain-local configuration directory |
|
61 2. The user-local configuration directory |
|
62 3. The global configuration directory |
|
63 |
|
64 The global configuration directory is set to `/etc/vmailmgr' by |
|
65 default. The user-local and domain-local configuration directories |
|
66 (for now, one and the same) are a subdirectory, named `.vmailmgr' by |
|
67 default, of either the user's home directory or the domain |
|
68 subdirectory. If a file matching the configuration name is found in |
|
69 one of the local directories, the search stops and it is not searched |
|
70 for in any higher up directories. |
|
71 |
|
72 1.2 File Types |
|
73 |
|
74 Each of the configuration files falls into one of the following types: |
|
75 String |
|
76 A single line is read from this type and used as-is with no |
|
77 conversion. All data after the first line is ignored. |
|
78 Directory |
|
79 A single line is read from this type. If it does not have a |
|
80 trailing slash (`/'), one is appended. All data after the first |
|
81 line is ignored. |
|
82 Number |
|
83 A single line is read from this type and converted to an |
|
84 unsigned integer. If the conversion succeeds, the value is |
|
85 used. All data after the first line is ignored. |
|
86 List |
|
87 Each line of the file is read, stripped of leading and trailing |
|
88 whitespace, and treated as a separate value. Lines that contain |
|
89 only whitespace (ie blank lines) or lines beginning with a |
|
90 pound symbol (`#') are ignored. |
|
91 Executable |
|
92 If the execute bits on the file are set, it is treated as an |
|
93 executable file and is executed with no interpretation by |
|
94 vmailmgr. The the Command Execution section below for details. |
|
95 |
|
96 All lines are stripped of any leading or trailing white space. |
|
97 |
|
98 Configuration files marked as `(global only)' are read before any |
|
99 user-level processing occurrs, and so are not functional in the |
|
100 user-level configuration. |
|
101 |
|
102 1.3 Command Execution |
|
103 |
|
104 The following rules apply to executing a single command or a list of |
|
105 commands. |
|
106 |
|
107 The executables are searched in reverse order of the configuration |
|
108 files. That is, the global setting is used first, and then the local |
|
109 settings. If the named file either does not exist in a directory or is |
|
110 not executable, that directory is skipped. |
|
111 |
|
112 A command exit code of `99' indicates that the command completed |
|
113 successfully but no further commands should be executed. All other |
|
114 non-zero exit codes are treated as an error and will cause the |
|
115 invoking program to stop with the same error code. For `vdeliver', an |
|
116 error exit of 111 will be passed up to qmail as a temporary error, and |
|
117 an error exit of 100 will be passed up as a permanent failure. See the |
|
118 `qmail-command' man page for full details on delivery error codes. For |
|
119 `checkvpw', any non-zero exit code (except as described above) will |
|
120 cause authentication to fail. |
|
121 |
|
122 The following environment variables will be set (where applicable): |
|
123 `HOME' |
|
124 The home directory of the real user. |
|
125 `MAILDIR' |
|
126 The mail directory of the real or virtual user. |
|
127 `USER' |
|
128 The real user's name. |
|
129 `VUSER' |
|
130 The virtual user's name. For base user logins, this is blank, |
|
131 and all the following items prefixed with `VUSER_' are not set. |
|
132 `VUSER_CTIME' |
|
133 The virtual user's creation time (or "0" if unknown). |
|
134 `VUSER_EXPIRY' |
|
135 The virtual user's expiry time (or "-" if not applicable). |
|
136 `VUSER_HARDQUOTA' |
|
137 The virtual user's total size hard quota (in bytes, or "-" if |
|
138 not applicable). |
|
139 `VUSER_MSGCOUNT' |
|
140 The virtual user's message count limit (or "-" if not |
|
141 applicable). |
|
142 `VUSER_MSGSIZE' |
|
143 The virtual user's message size limit (or "-" if not |
|
144 applicable). |
|
145 `VUSER_PERSONAL' |
|
146 The virtual user's personal data. |
|
147 `VUSER_SOFTQUOTA' |
|
148 The virtual user's total size soft quota (in bytes, or "-" if |
|
149 not applicable). |
|
150 |
|
151 2. Configuration Files |
|
152 |
|
153 Each of the following sections identifies a single configuration file |
|
154 |
|
155 2.1 authvmailmgr-error |
|
156 |
|
157 Type |
|
158 executable |
|
159 Default |
|
160 Empty |
|
161 Used By |
|
162 authvmailmgr |
|
163 Description |
|
164 This is executed by authvmailmgr if any error occurrs other |
|
165 than those caught by `authvmailmgr-loginfail' below. The |
|
166 environment variable AUTHVMAILMGR_ERROR will contain an error |
|
167 message. This can be used to output logging messages about |
|
168 errors in authvmailmgr. |
|
169 |
|
170 2.2 authvmailmgr-loginfail |
|
171 |
|
172 Type |
|
173 executable |
|
174 Default |
|
175 Empty |
|
176 Used By |
|
177 authvmailmgr |
|
178 Description |
|
179 This is executed by authvmailmgr if the user's login fails. The |
|
180 environment variable AUTHVMAILMGR_ERROR will contain an error |
|
181 message. The environment variable VUSER will be set to the |
|
182 virtual user name if it has been determined. This can be used |
|
183 to output logging messages about login failures or to throttle |
|
184 hackers. |
|
185 |
|
186 2.3 authvmailmgr-postsetuid |
|
187 |
|
188 Type |
|
189 executable |
|
190 Default |
|
191 @samp {vpopbull} |
|
192 Used By |
|
193 authvmailmgr |
|
194 Description |
|
195 This is executed by authvmailmgr after a user is successfully |
|
196 authenticated. |
|
197 |
|
198 2.4 authvmailmgr-presetuid |
|
199 |
|
200 Type |
|
201 executable |
|
202 Default |
|
203 Empty |
|
204 Used By |
|
205 authvmailmgr |
|
206 Description |
|
207 This list is executed by authvmailmgr before changing user away |
|
208 from root, and before authenticating a virtual user. Note: The |
|
209 environment variable `MAILDIR' is not set since the virtual |
|
210 user has not yet been authenticated, or even looked up at this |
|
211 point. For the same reason, `VUSER' is not authenticated and is |
|
212 under complete control of the invoking user. |
|
213 |
|
214 2.5 autoresponse-dir |
|
215 |
|
216 Type |
|
217 directory |
|
218 Default |
|
219 `autoresponse' |
|
220 Used By |
|
221 vmailmgrd, autoresponder script |
|
222 Description |
|
223 Identifies the subdirectory of the virtual user directory in |
|
224 which all autoresponse data is stored. |
|
225 |
|
226 2.6 autoresponse-file |
|
227 |
|
228 Type |
|
229 string |
|
230 Default |
|
231 `message.txt' |
|
232 Used By |
|
233 vmailmgrd, autoresponder script |
|
234 Description |
|
235 Identifies the file name within the autoresponse directory that |
|
236 contains the autoresponse message. |
|
237 |
|
238 2.7 bulletin-dir |
|
239 |
|
240 Type |
|
241 directory |
|
242 Default |
|
243 `bulletins' |
|
244 Used By |
|
245 checkvpw |
|
246 Description |
|
247 Identifies the subdirectory of the domain directory in which |
|
248 bulletins local to a domain are stored. |
|
249 |
|
250 2.8 checkvpw-error |
|
251 |
|
252 Type |
|
253 executable |
|
254 Default |
|
255 Empty |
|
256 Used By |
|
257 checkvpw |
|
258 Description |
|
259 This is executed by checkvpw if any error occurrs other than |
|
260 those caught by `checkvpw-loginfail' below. The environment |
|
261 variable CHECKVPW_ERROR will contain an error message. This can |
|
262 be used to output logging messages about errors in checkvpw. |
|
263 |
|
264 2.9 checkvpw-loginfail |
|
265 |
|
266 Type |
|
267 executable |
|
268 Default |
|
269 Empty |
|
270 Used By |
|
271 checkvpw |
|
272 Description |
|
273 This is executed by checkvpw if the user's login fails. The |
|
274 environment variable CHECKVPW_ERROR will contain an error |
|
275 message. The environment variable VUSER will be set to the |
|
276 virtual user name if it has been determined. This can be used |
|
277 to output logging messages about login failures or to throttle |
|
278 hackers. |
|
279 |
|
280 2.10 checkvpw-postexec |
|
281 |
|
282 Type |
|
283 executable |
|
284 Default |
|
285 Empty |
|
286 Used By |
|
287 checkvpw |
|
288 Description |
|
289 This is executed by checkvpw after the subcommand successfully |
|
290 completes. |
|
291 |
|
292 2.11 checkvpw-postsetuid |
|
293 |
|
294 Type |
|
295 executable |
|
296 Default |
|
297 @samp {vpopbull} |
|
298 Used By |
|
299 checkvpw |
|
300 Description |
|
301 This is executed by checkvpw after a user is successfully |
|
302 authenticated. |
|
303 |
|
304 2.12 checkvpw-presetuid |
|
305 |
|
306 Type |
|
307 executable |
|
308 Default |
|
309 Empty |
|
310 Used By |
|
311 checkvpw |
|
312 Description |
|
313 This list is executed by checkvpw before changing user away |
|
314 from root, and before authenticating a virtual user. Note: The |
|
315 environment variable `MAILDIR' is not set since the virtual |
|
316 user has not yet been authenticated, or even looked up at this |
|
317 point. For the same reason, `VUSER' is not authenticated and is |
|
318 under complete control of the invoking user. |
|
319 |
|
320 2.13 default-expiry |
|
321 |
|
322 Type |
|
323 number |
|
324 Default |
|
325 `-1' |
|
326 Used By |
|
327 vadduser |
|
328 Description |
|
329 Sets the default expiry value for newly created users. Negative |
|
330 values indicate no expiry. |
|
331 |
|
332 2.14 default-maildir |
|
333 |
|
334 Type |
|
335 directory |
|
336 Default |
|
337 `Maildir' |
|
338 Used By |
|
339 checkvpw |
|
340 Description |
|
341 Sets the name of the directory to be used as a non-virtual |
|
342 user's maildir. |
|
343 |
|
344 2.15 default-msgcount |
|
345 |
|
346 Type |
|
347 number |
|
348 Default |
|
349 `-1' |
|
350 Used By |
|
351 vadduser |
|
352 Description |
|
353 Sets the default message count limit. |
|
354 |
|
355 2.16 default-msgsize |
|
356 |
|
357 Type |
|
358 number |
|
359 Default |
|
360 `-1' |
|
361 Used By |
|
362 vadduser |
|
363 Description |
|
364 Sets the default message size limit, in bytes. |
|
365 |
|
366 2.17 default-hardquota |
|
367 |
|
368 Type |
|
369 number |
|
370 Default |
|
371 `-1' |
|
372 Used By |
|
373 vadduser |
|
374 Description |
|
375 Sets the default hard quota, in bytes. |
|
376 |
|
377 2.18 default-softquota |
|
378 |
|
379 Type |
|
380 number |
|
381 Default |
|
382 `-1' |
|
383 Used By |
|
384 vadduser |
|
385 Description |
|
386 Sets the default soft quota, in bytes. |
|
387 |
|
388 2.19 default-username |
|
389 |
|
390 Type |
|
391 string |
|
392 Default |
|
393 `+' |
|
394 Used By |
|
395 vmailmgrd |
|
396 Description |
|
397 Identifies the name of the virtual user to be looked up if a |
|
398 lookup of another virtual user fails. |
|
399 |
|
400 2.20 error-maildir |
|
401 |
|
402 Type |
|
403 directory |
|
404 Default |
|
405 `/var/lib/vmailmgr/error-maildir' |
|
406 Used By |
|
407 checkvpw |
|
408 Description |
|
409 Specifies the path of a read-only maildir containing a message |
|
410 to be sent to the user when the maildir corresponding to that |
|
411 user does not exist. |
|
412 |
|
413 2.21 global-bulletin-dir |
|
414 |
|
415 Type |
|
416 directory |
|
417 Default |
|
418 `/var/spool/bulletins' |
|
419 Used By |
|
420 checkvpw |
|
421 Description |
|
422 Identifies a site-wide bulletin directory. |
|
423 |
|
424 2.22 maildir-arg-str |
|
425 |
|
426 Type |
|
427 string |
|
428 Default |
|
429 `maildir' |
|
430 Used By |
|
431 checkvpw (global only) |
|
432 Description |
|
433 Identifies the string to search for when attempting to identify |
|
434 the maildir argument on the command line to checkvpw. |
|
435 |
|
436 2.23 password-file |
|
437 |
|
438 Type |
|
439 string |
|
440 Default |
|
441 `passwd' |
|
442 Used By |
|
443 vmailmgrd and command-line programs |
|
444 Description |
|
445 Identifies the file that contains user names, passwords, and |
|
446 destinations for a virtual domain. Note that this has nothing |
|
447 to do with "real" users, for which the password file is |
|
448 determined by the system libraries. |
|
449 |
|
450 2.24 postmaster-aliases |
|
451 |
|
452 Type |
|
453 list |
|
454 Default |
|
455 `mailer-daemon' `postmaster' `root' |
|
456 Used By |
|
457 vsetup |
|
458 Description |
|
459 A list of aliases to the postmaster email address to set up |
|
460 when creating a new virtual domain with the vsetup command. |
|
461 This should always contain both `postmaster' and |
|
462 `mailer-daemon' (required by the RFCs), and should usually |
|
463 contain `root'. |
|
464 |
|
465 2.25 postmaster-email |
|
466 |
|
467 Type |
|
468 string |
|
469 Default |
|
470 `postmaster@' |
|
471 Used By |
|
472 vsetup |
|
473 Description |
|
474 Identifies the email address of the entity responsible for the |
|
475 administration of the (virtual) host when building the |
|
476 postmaster aliases above. If this value ends with a trailing |
|
477 `@', the value of `/var/qmail/control/me' is filled in for the |
|
478 host name. If no `@' is present, the current virtual host name |
|
479 is filled in by vdeliver. If this is set to `postmaster', a |
|
480 mail loop will result and all mail to this address will bounce. |
|
481 |
|
482 2.26 qmail-root |
|
483 |
|
484 Type |
|
485 string |
|
486 Default |
|
487 `/var/qmail' |
|
488 Used By |
|
489 checkvpw, vdeliver, vmailmgrd |
|
490 Description |
|
491 Specifies the location of the base directory of your qmail |
|
492 install. Set this to whatever you put into `conf-home' when you |
|
493 built and installed qmail. |
|
494 |
|
495 2.27 separators |
|
496 |
|
497 Type |
|
498 string |
|
499 Default |
|
500 `@:' |
|
501 Used By |
|
502 checkvpw (global only) |
|
503 Description |
|
504 Identifies the set of valid separators within a user login name |
|
505 between the virtual user name and virtual domain name when |
|
506 logging in via checkvpw. For example, if separators contains |
|
507 `@:' then `user@domain' and `user:domain' are equivalent POP |
|
508 mailbox names. |
|
509 |
|
510 2.28 socket-file |
|
511 |
|
512 Type |
|
513 string |
|
514 Default |
|
515 `/tmp/.vmailmgrd' |
|
516 Used By |
|
517 vmailmgrd, checkvpw, vdeliver, and the CGI programs |
|
518 Description |
|
519 Identifies the file name of the local socket used to |
|
520 communicate between the vmailmgr daemon and the other programs. |
|
521 Warning: Changing this in the local configuration directories |
|
522 will cause vdeliver to fail. |
|
523 |
|
524 2.29 user-dir |
|
525 |
|
526 Type |
|
527 directory |
|
528 Default |
|
529 `users' |
|
530 Used By |
|
531 vmailmgrd and command-line programs |
|
532 Description |
|
533 Identifies the subdirectory from the virtual domain directory |
|
534 in which a virtual user's maildir will be created. Since this |
|
535 maildir is recorded in the password table, it does not have to |
|
536 be the same for each user within a domain. This is prefixed |
|
537 with `./' before it is used in the password table. |
|
538 |
|
539 2.30 user-dir-bits |
|
540 |
|
541 Type |
|
542 Default |
|
543 `0' |
|
544 Used By |
|
545 vmailmgrd and command-line programs when creating new users. |
|
546 Description |
|
547 See section 2.31 user-dir-slices |
|
548 |
|
549 2.31 user-dir-slices |
|
550 |
|
551 Type |
|
552 Default |
|
553 `0' |
|
554 Used By |
|
555 vmailmgrd and command-line programs when creating new users. |
|
556 Description |
|
557 `user-dir-bits' and `user-dir-slices' work together. When |
|
558 creating a new user directory name, a hash code is generated on |
|
559 the name of the new user. This hash code is split into |
|
560 `user-dir-slices' pieces, each `user-dir-bits' bits long. Each |
|
561 of these pieces is translated to an ASCII string by converting |
|
562 the binary code to hexadecimal. The resulting user directory |
|
563 name is then composed of: |
|
564 + the base users directory, followed by a `/' |
|
565 + each of the string pieces, each followed by a `/' |
|
566 + the user's name |
|
567 For example, with `user-dir-bits' set to 6 and |
|
568 `user-dir-slices' set to 1, a user named `c' maps to a |
|
569 directory name of `users/2f/c/'. |
|
570 |
|
571 2.32 vdeliver-postdeliver |
|
572 |
|
573 Type |
|
574 executable |
|
575 Default |
|
576 Empty |
|
577 Used By |
|
578 vdeliver |
|
579 Description |
|
580 This list is executed after the delivery is successfully |
|
581 completed. Since vdeliver expects `USER' and `HOME' to be set, |
|
582 it does not set them itself. If the command returns with an |
|
583 error code, a warning is printed, but delivery does not fail, |
|
584 as failure would lead to duplicates. |
|
585 |
|
586 2.33 vdeliver-predeliver |
|
587 |
|
588 Type |
|
589 executable |
|
590 Default |
|
591 Empty |
|
592 Used By |
|
593 vdeliver |
|
594 Description |
|
595 This list is executed before the delivery is attempted, but |
|
596 after the virtual user information is looked up. Since vdeliver |
|
597 expects `USER' and `HOME' to be set, it does not set them |
|
598 itself. |
|
599 |
|
600 2.34 vsetup-pre |
|
601 |
|
602 Type |
|
603 executable |
|
604 Default |
|
605 Empty |
|
606 Used By |
|
607 vsetup |
|
608 Description |
|
609 This list is executed after the vsetup command has sucessfully |
|
610 done everything else. |
|
611 |
|
612 2.35 vsetup-pre |
|
613 |
|
614 Type |
|
615 executable |
|
616 Default |
|
617 Empty |
|
618 Used By |
|
619 vsetup |
|
620 Description |
|
621 This list is executed before the vsetup command makes any |
|
622 changes. |
|
623 _________________________________________________________________ |
|
624 |
|
625 This document was generated on 14 September 2000 using |
|
626 texi2html 1.56k. |