diff -r 30113bfbe723 -r b3afb9f1e801 doc/configuration.info
--- /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