
                         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.
