     Copyright (C) 1998 Bruce Guenter

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*
     `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*
     `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 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-post
================

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