--- /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.