--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/configuration.info Sun Jan 20 00:22:09 2008 +0100
@@ -0,0 +1,952 @@
+This is configuration.info, produced by makeinfo version 4.7 from
+configuration.texi.
+
+ Copyright (C) 1998 Bruce Guenter
+
+
+File: configuration.info, Node: Top, Next: General Information, Prev: (dir), Up: (dir)
+
+* Menu:
+
+* General Information::
+* Configuration Files::
+
+
+File: configuration.info, Node: General Information, Next: Configuration Files, Prev: Top, Up: Top
+
+1 General Information
+*********************
+
+* Menu:
+
+* Search Order::
+* File Types::
+* Command Execution::
+
+
+File: configuration.info, Node: Search Order, Next: File Types, Prev: General Information, Up: 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.
+
+
+File: configuration.info, Node: File Types, Next: Command Execution, Prev: Search Order, Up: General Information
+
+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.
+
+
+File: configuration.info, Node: Command Execution, Prev: File Types, Up: General Information
+
+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).
+
+
+File: configuration.info, Node: Configuration Files, Prev: General Information, Up: Top
+
+2 Configuration Files
+*********************
+
+Each of the following sections identifies a single configuration file
+
+* Menu:
+
+* authvmailmgr-error::
+* authvmailmgr-loginfail::
+* authvmailmgr-postsetuid::
+* authvmailmgr-presetuid::
+* autoresponse-dir::
+* autoresponse-file::
+* bulletin-dir::
+* checkvpw-error::
+* checkvpw-loginfail::
+* checkvpw-postexec::
+* checkvpw-postsetuid::
+* checkvpw-presetuid::
+* default-expiry::
+* default-maildir::
+* default-msgcount::
+* default-msgsize::
+* default-hardquota::
+* default-softquota::
+* default-username::
+* error-maildir::
+* global-bulletin-dir::
+* maildir-arg-str::
+* password-file::
+* postmaster-aliases::
+* postmaster-email::
+* qmail-root::
+* separators::
+* socket-file::
+* user-dir::
+* user-dir-bits::
+* user-dir-slices::
+* vdeliver-postdeliver::
+* vdeliver-predeliver::
+* vsetup-post::
+* vsetup-pre::
+
+
+File: configuration.info, Node: authvmailmgr-error, Next: authvmailmgr-loginfail, Prev: Configuration Files, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: authvmailmgr-loginfail, Next: authvmailmgr-postsetuid, Prev: authvmailmgr-error, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: authvmailmgr-postsetuid, Next: authvmailmgr-presetuid, Prev: authvmailmgr-loginfail, Up: Configuration Files
+
+2.3 authvmailmgr-postsetuid
+===========================
+
+*Type*
+ executable
+
+*Default*
+ `vpopbull'
+
+*Used By*
+ authvmailmgr
+
+*Description*
+ This is executed by authvmailmgr after a user is successfully
+ authenticated.
+
+
+File: configuration.info, Node: authvmailmgr-presetuid, Next: autoresponse-dir, Prev: authvmailmgr-postsetuid, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: autoresponse-dir, Next: autoresponse-file, Prev: authvmailmgr-presetuid, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: autoresponse-file, Next: bulletin-dir, Prev: autoresponse-dir, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: bulletin-dir, Next: checkvpw-error, Prev: autoresponse-file, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: checkvpw-error, Next: checkvpw-loginfail, Prev: bulletin-dir, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: checkvpw-loginfail, Next: checkvpw-postexec, Prev: checkvpw-error, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: checkvpw-postexec, Next: checkvpw-postsetuid, Prev: checkvpw-loginfail, Up: Configuration Files
+
+2.10 checkvpw-postexec
+======================
+
+*Type*
+ executable
+
+*Default*
+ Empty
+
+*Used By*
+ checkvpw
+
+*Description*
+ This is executed by checkvpw after the subcommand successfully
+ completes.
+
+
+File: configuration.info, Node: checkvpw-postsetuid, Next: checkvpw-presetuid, Prev: checkvpw-postexec, Up: Configuration Files
+
+2.11 checkvpw-postsetuid
+========================
+
+*Type*
+ executable
+
+*Default*
+ `vpopbull'
+
+*Used By*
+ checkvpw
+
+*Description*
+ This is executed by checkvpw after a user is successfully
+ authenticated.
+
+
+File: configuration.info, Node: checkvpw-presetuid, Next: default-expiry, Prev: checkvpw-postsetuid, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: default-expiry, Next: default-maildir, Prev: checkvpw-presetuid, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: default-maildir, Next: default-msgcount, Prev: default-expiry, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: default-msgcount, Next: default-msgsize, Prev: default-maildir, Up: Configuration Files
+
+2.15 default-msgcount
+=====================
+
+*Type*
+ number
+
+*Default*
+ `-1'
+
+*Used By*
+ vadduser
+
+*Description*
+ Sets the default message count limit.
+
+
+File: configuration.info, Node: default-msgsize, Next: default-hardquota, Prev: default-msgcount, Up: Configuration Files
+
+2.16 default-msgsize
+====================
+
+*Type*
+ number
+
+*Default*
+ `-1'
+
+*Used By*
+ vadduser
+
+*Description*
+ Sets the default message size limit, in bytes.
+
+
+File: configuration.info, Node: default-hardquota, Next: default-softquota, Prev: default-msgsize, Up: Configuration Files
+
+2.17 default-hardquota
+======================
+
+*Type*
+ number
+
+*Default*
+ `-1'
+
+*Used By*
+ vadduser
+
+*Description*
+ Sets the default hard quota, in bytes.
+
+
+File: configuration.info, Node: default-softquota, Next: default-username, Prev: default-hardquota, Up: Configuration Files
+
+2.18 default-softquota
+======================
+
+*Type*
+ number
+
+*Default*
+ `-1'
+
+*Used By*
+ vadduser
+
+*Description*
+ Sets the default soft quota, in bytes.
+
+
+File: configuration.info, Node: default-username, Next: error-maildir, Prev: default-softquota, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: error-maildir, Next: global-bulletin-dir, Prev: default-username, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: global-bulletin-dir, Next: maildir-arg-str, Prev: error-maildir, Up: Configuration Files
+
+2.21 global-bulletin-dir
+========================
+
+*Type*
+ directory
+
+*Default*
+ `/var/spool/bulletins'
+
+*Used By*
+ checkvpw
+
+*Description*
+ Identifies a site-wide bulletin directory.
+
+
+File: configuration.info, Node: maildir-arg-str, Next: password-file, Prev: global-bulletin-dir, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: password-file, Next: postmaster-aliases, Prev: maildir-arg-str, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: postmaster-aliases, Next: postmaster-email, Prev: password-file, Up: Configuration Files
+
+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'.
+
+
+File: configuration.info, Node: postmaster-email, Next: qmail-root, Prev: postmaster-aliases, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: qmail-root, Next: separators, Prev: postmaster-email, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: separators, Next: socket-file, Prev: qmail-root, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: socket-file, Next: user-dir, Prev: separators, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: user-dir, Next: user-dir-bits, Prev: socket-file, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: user-dir-bits, Next: user-dir-slices, Prev: user-dir, Up: Configuration Files
+
+2.30 user-dir-bits
+==================
+
+*Type*
+
+*Default*
+ `0'
+
+*Used By*
+ vmailmgrd and command-line programs when creating new users.
+
+*Description*
+ *Note user-dir-slices::.
+
+
+File: configuration.info, Node: user-dir-slices, Next: vdeliver-postdeliver, Prev: user-dir-bits, Up: Configuration Files
+
+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/'.
+
+
+File: configuration.info, Node: vdeliver-postdeliver, Next: vdeliver-predeliver, Prev: user-dir-slices, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: vdeliver-predeliver, Next: vsetup-post, Prev: vdeliver-postdeliver, Up: Configuration Files
+
+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.
+
+
+File: configuration.info, Node: vsetup-post, Next: vsetup-pre, Prev: vdeliver-predeliver, Up: Configuration Files
+
+2.34 vsetup-post
+================
+
+*Type*
+ executable
+
+*Default*
+ Empty
+
+*Used By*
+ vsetup
+
+*Description*
+ This list is executed after the vsetup command has sucessfully done
+ everything else.
+
+
+File: configuration.info, Node: vsetup-pre, Prev: vsetup-post, Up: Configuration Files
+
+2.35 vsetup-pre
+===============
+
+*Type*
+ executable
+
+*Default*
+ Empty
+
+*Used By*
+ vsetup
+
+*Description*
+ This list is executed before the vsetup command makes any changes.
+
+
+
+Tag Table:
+Node: Top126
+Node: General Information278
+Node: Search Order493
+Node: File Types1358
+Node: Command Execution2759
+Node: Configuration Files4801
+Node: authvmailmgr-error5743
+Node: authvmailmgr-loginfail6311
+Node: authvmailmgr-postsetuid6956
+Node: authvmailmgr-presetuid7343
+Node: autoresponse-dir8020
+Node: autoresponse-file8426
+Node: bulletin-dir8819
+Node: checkvpw-error9180
+Node: checkvpw-loginfail9700
+Node: checkvpw-postexec10311
+Node: checkvpw-postsetuid10663
+Node: checkvpw-presetuid11023
+Node: default-expiry11676
+Node: default-maildir12028
+Node: default-msgcount12371
+Node: default-msgsize12667
+Node: default-hardquota12972
+Node: default-softquota13274
+Node: default-username13577
+Node: error-maildir13939
+Node: global-bulletin-dir14381
+Node: maildir-arg-str14710
+Node: password-file15109
+Node: postmaster-aliases15623
+Node: postmaster-email16175
+Node: qmail-root16900
+Node: separators17325
+Node: socket-file17846
+Node: user-dir18359
+Node: user-dir-bits18940
+Node: user-dir-slices19246
+Node: vdeliver-postdeliver20259
+Node: vdeliver-predeliver20838
+Node: vsetup-post21312
+Node: vsetup-pre21647
+
+End Tag Table