diff -r 000000000000 -r 6f7a81934006 doc/configuration.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/configuration.txt Wed Jan 16 22:39:43 2008 +0100 @@ -0,0 +1,626 @@ + + Vmailmgr Configuration Files + +14 September 2000 + + + Bruce Guenter + _________________________________________________________________ + + Table of Contents + + * 1. General Information + + 1.1 Search Order + + 1.2 File Types + + 1.3 Command Execution + * 2. Configuration Files + + 2.1 authvmailmgr-error + + 2.2 authvmailmgr-loginfail + + 2.3 authvmailmgr-postsetuid + + 2.4 authvmailmgr-presetuid + + 2.5 autoresponse-dir + + 2.6 autoresponse-file + + 2.7 bulletin-dir + + 2.8 checkvpw-error + + 2.9 checkvpw-loginfail + + 2.10 checkvpw-postexec + + 2.11 checkvpw-postsetuid + + 2.12 checkvpw-presetuid + + 2.13 default-expiry + + 2.14 default-maildir + + 2.15 default-msgcount + + 2.16 default-msgsize + + 2.17 default-hardquota + + 2.18 default-softquota + + 2.19 default-username + + 2.20 error-maildir + + 2.21 global-bulletin-dir + + 2.22 maildir-arg-str + + 2.23 password-file + + 2.24 postmaster-aliases + + 2.25 postmaster-email + + 2.26 qmail-root + + 2.27 separators + + 2.28 socket-file + + 2.29 user-dir + + 2.30 user-dir-bits + + 2.31 user-dir-slices + + 2.32 vdeliver-postdeliver + + 2.33 vdeliver-predeliver + + 2.34 vsetup-pre + + 2.35 vsetup-pre + _________________________________________________________________ + + 1. General Information + +1.1 Search Order + + The system will look for the configuration files listed below in one + of the following three locations, in the order they are listed: + 1. The domain-local configuration directory + 2. The user-local configuration directory + 3. The global configuration directory + + The global configuration directory is set to `/etc/vmailmgr' by + default. The user-local and domain-local configuration directories + (for now, one and the same) are a subdirectory, named `.vmailmgr' by + default, of either the user's home directory or the domain + subdirectory. If a file matching the configuration name is found in + one of the local directories, the search stops and it is not searched + for in any higher up directories. + +1.2 File Types + + Each of the configuration files falls into one of the following types: + String + A single line is read from this type and used as-is with no + conversion. All data after the first line is ignored. + Directory + A single line is read from this type. If it does not have a + trailing slash (`/'), one is appended. All data after the first + line is ignored. + Number + A single line is read from this type and converted to an + unsigned integer. If the conversion succeeds, the value is + used. All data after the first line is ignored. + List + Each line of the file is read, stripped of leading and trailing + whitespace, and treated as a separate value. Lines that contain + only whitespace (ie blank lines) or lines beginning with a + pound symbol (`#') are ignored. + Executable + If the execute bits on the file are set, it is treated as an + executable file and is executed with no interpretation by + vmailmgr. The the Command Execution section below for details. + + All lines are stripped of any leading or trailing white space. + + Configuration files marked as `(global only)' are read before any + user-level processing occurrs, and so are not functional in the + user-level configuration. + +1.3 Command Execution + + The following rules apply to executing a single command or a list of + commands. + + The executables are searched in reverse order of the configuration + files. That is, the global setting is used first, and then the local + settings. If the named file either does not exist in a directory or is + not executable, that directory is skipped. + + A command exit code of `99' indicates that the command completed + successfully but no further commands should be executed. All other + non-zero exit codes are treated as an error and will cause the + invoking program to stop with the same error code. For `vdeliver', an + error exit of 111 will be passed up to qmail as a temporary error, and + an error exit of 100 will be passed up as a permanent failure. See the + `qmail-command' man page for full details on delivery error codes. For + `checkvpw', any non-zero exit code (except as described above) will + cause authentication to fail. + + The following environment variables will be set (where applicable): + `HOME' + The home directory of the real user. + `MAILDIR' + The mail directory of the real or virtual user. + `USER' + The real user's name. + `VUSER' + The virtual user's name. For base user logins, this is blank, + and all the following items prefixed with `VUSER_' are not set. + `VUSER_CTIME' + The virtual user's creation time (or "0" if unknown). + `VUSER_EXPIRY' + The virtual user's expiry time (or "-" if not applicable). + `VUSER_HARDQUOTA' + The virtual user's total size hard quota (in bytes, or "-" if + not applicable). + `VUSER_MSGCOUNT' + The virtual user's message count limit (or "-" if not + applicable). + `VUSER_MSGSIZE' + The virtual user's message size limit (or "-" if not + applicable). + `VUSER_PERSONAL' + The virtual user's personal data. + `VUSER_SOFTQUOTA' + The virtual user's total size soft quota (in bytes, or "-" if + not applicable). + + 2. Configuration Files + + Each of the following sections identifies a single configuration file + +2.1 authvmailmgr-error + + Type + executable + Default + Empty + Used By + authvmailmgr + Description + This is executed by authvmailmgr if any error occurrs other + than those caught by `authvmailmgr-loginfail' below. The + environment variable AUTHVMAILMGR_ERROR will contain an error + message. This can be used to output logging messages about + errors in authvmailmgr. + +2.2 authvmailmgr-loginfail + + Type + executable + Default + Empty + Used By + authvmailmgr + Description + This is executed by authvmailmgr if the user's login fails. The + environment variable AUTHVMAILMGR_ERROR will contain an error + message. The environment variable VUSER will be set to the + virtual user name if it has been determined. This can be used + to output logging messages about login failures or to throttle + hackers. + +2.3 authvmailmgr-postsetuid + + Type + executable + Default + @samp {vpopbull} + Used By + authvmailmgr + Description + This is executed by authvmailmgr after a user is successfully + authenticated. + +2.4 authvmailmgr-presetuid + + Type + executable + Default + Empty + Used By + authvmailmgr + Description + This list is executed by authvmailmgr before changing user away + from root, and before authenticating a virtual user. Note: The + environment variable `MAILDIR' is not set since the virtual + user has not yet been authenticated, or even looked up at this + point. For the same reason, `VUSER' is not authenticated and is + under complete control of the invoking user. + +2.5 autoresponse-dir + + Type + directory + Default + `autoresponse' + Used By + vmailmgrd, autoresponder script + Description + Identifies the subdirectory of the virtual user directory in + which all autoresponse data is stored. + +2.6 autoresponse-file + + Type + string + Default + `message.txt' + Used By + vmailmgrd, autoresponder script + Description + Identifies the file name within the autoresponse directory that + contains the autoresponse message. + +2.7 bulletin-dir + + Type + directory + Default + `bulletins' + Used By + checkvpw + Description + Identifies the subdirectory of the domain directory in which + bulletins local to a domain are stored. + +2.8 checkvpw-error + + Type + executable + Default + Empty + Used By + checkvpw + Description + This is executed by checkvpw if any error occurrs other than + those caught by `checkvpw-loginfail' below. The environment + variable CHECKVPW_ERROR will contain an error message. This can + be used to output logging messages about errors in checkvpw. + +2.9 checkvpw-loginfail + + Type + executable + Default + Empty + Used By + checkvpw + Description + This is executed by checkvpw if the user's login fails. The + environment variable CHECKVPW_ERROR will contain an error + message. The environment variable VUSER will be set to the + virtual user name if it has been determined. This can be used + to output logging messages about login failures or to throttle + hackers. + +2.10 checkvpw-postexec + + Type + executable + Default + Empty + Used By + checkvpw + Description + This is executed by checkvpw after the subcommand successfully + completes. + +2.11 checkvpw-postsetuid + + Type + executable + Default + @samp {vpopbull} + Used By + checkvpw + Description + This is executed by checkvpw after a user is successfully + authenticated. + +2.12 checkvpw-presetuid + + Type + executable + Default + Empty + Used By + checkvpw + Description + This list is executed by checkvpw before changing user away + from root, and before authenticating a virtual user. Note: The + environment variable `MAILDIR' is not set since the virtual + user has not yet been authenticated, or even looked up at this + point. For the same reason, `VUSER' is not authenticated and is + under complete control of the invoking user. + +2.13 default-expiry + + Type + number + Default + `-1' + Used By + vadduser + Description + Sets the default expiry value for newly created users. Negative + values indicate no expiry. + +2.14 default-maildir + + Type + directory + Default + `Maildir' + Used By + checkvpw + Description + Sets the name of the directory to be used as a non-virtual + user's maildir. + +2.15 default-msgcount + + Type + number + Default + `-1' + Used By + vadduser + Description + Sets the default message count limit. + +2.16 default-msgsize + + Type + number + Default + `-1' + Used By + vadduser + Description + Sets the default message size limit, in bytes. + +2.17 default-hardquota + + Type + number + Default + `-1' + Used By + vadduser + Description + Sets the default hard quota, in bytes. + +2.18 default-softquota + + Type + number + Default + `-1' + Used By + vadduser + Description + Sets the default soft quota, in bytes. + +2.19 default-username + + Type + string + Default + `+' + Used By + vmailmgrd + Description + Identifies the name of the virtual user to be looked up if a + lookup of another virtual user fails. + +2.20 error-maildir + + Type + directory + Default + `/var/lib/vmailmgr/error-maildir' + Used By + checkvpw + Description + Specifies the path of a read-only maildir containing a message + to be sent to the user when the maildir corresponding to that + user does not exist. + +2.21 global-bulletin-dir + + Type + directory + Default + `/var/spool/bulletins' + Used By + checkvpw + Description + Identifies a site-wide bulletin directory. + +2.22 maildir-arg-str + + Type + string + Default + `maildir' + Used By + checkvpw (global only) + Description + Identifies the string to search for when attempting to identify + the maildir argument on the command line to checkvpw. + +2.23 password-file + + Type + string + Default + `passwd' + Used By + vmailmgrd and command-line programs + Description + Identifies the file that contains user names, passwords, and + destinations for a virtual domain. Note that this has nothing + to do with "real" users, for which the password file is + determined by the system libraries. + +2.24 postmaster-aliases + + Type + list + Default + `mailer-daemon' `postmaster' `root' + Used By + vsetup + Description + A list of aliases to the postmaster email address to set up + when creating a new virtual domain with the vsetup command. + This should always contain both `postmaster' and + `mailer-daemon' (required by the RFCs), and should usually + contain `root'. + +2.25 postmaster-email + + Type + string + Default + `postmaster@' + Used By + vsetup + Description + Identifies the email address of the entity responsible for the + administration of the (virtual) host when building the + postmaster aliases above. If this value ends with a trailing + `@', the value of `/var/qmail/control/me' is filled in for the + host name. If no `@' is present, the current virtual host name + is filled in by vdeliver. If this is set to `postmaster', a + mail loop will result and all mail to this address will bounce. + +2.26 qmail-root + + Type + string + Default + `/var/qmail' + Used By + checkvpw, vdeliver, vmailmgrd + Description + Specifies the location of the base directory of your qmail + install. Set this to whatever you put into `conf-home' when you + built and installed qmail. + +2.27 separators + + Type + string + Default + `@:' + Used By + checkvpw (global only) + Description + Identifies the set of valid separators within a user login name + between the virtual user name and virtual domain name when + logging in via checkvpw. For example, if separators contains + `@:' then `user@domain' and `user:domain' are equivalent POP + mailbox names. + +2.28 socket-file + + Type + string + Default + `/tmp/.vmailmgrd' + Used By + vmailmgrd, checkvpw, vdeliver, and the CGI programs + Description + Identifies the file name of the local socket used to + communicate between the vmailmgr daemon and the other programs. + Warning: Changing this in the local configuration directories + will cause vdeliver to fail. + +2.29 user-dir + + Type + directory + Default + `users' + Used By + vmailmgrd and command-line programs + Description + Identifies the subdirectory from the virtual domain directory + in which a virtual user's maildir will be created. Since this + maildir is recorded in the password table, it does not have to + be the same for each user within a domain. This is prefixed + with `./' before it is used in the password table. + +2.30 user-dir-bits + + Type + Default + `0' + Used By + vmailmgrd and command-line programs when creating new users. + Description + See section 2.31 user-dir-slices + +2.31 user-dir-slices + + Type + Default + `0' + Used By + vmailmgrd and command-line programs when creating new users. + Description + `user-dir-bits' and `user-dir-slices' work together. When + creating a new user directory name, a hash code is generated on + the name of the new user. This hash code is split into + `user-dir-slices' pieces, each `user-dir-bits' bits long. Each + of these pieces is translated to an ASCII string by converting + the binary code to hexadecimal. The resulting user directory + name is then composed of: + + the base users directory, followed by a `/' + + each of the string pieces, each followed by a `/' + + the user's name + For example, with `user-dir-bits' set to 6 and + `user-dir-slices' set to 1, a user named `c' maps to a + directory name of `users/2f/c/'. + +2.32 vdeliver-postdeliver + + Type + executable + Default + Empty + Used By + vdeliver + Description + This list is executed after the delivery is successfully + completed. Since vdeliver expects `USER' and `HOME' to be set, + it does not set them itself. If the command returns with an + error code, a warning is printed, but delivery does not fail, + as failure would lead to duplicates. + +2.33 vdeliver-predeliver + + Type + executable + Default + Empty + Used By + vdeliver + Description + This list is executed before the delivery is attempted, but + after the virtual user information is looked up. Since vdeliver + expects `USER' and `HOME' to be set, it does not set them + itself. + +2.34 vsetup-pre + + Type + executable + Default + Empty + Used By + vsetup + Description + This list is executed after the vsetup command has sucessfully + done everything else. + +2.35 vsetup-pre + + Type + executable + Default + Empty + Used By + vsetup + Description + This list is executed before the vsetup command makes any + changes. + _________________________________________________________________ + + This document was generated on 14 September 2000 using + texi2html 1.56k.