diff -r 000000000000 -r 6f7a81934006 doc/configuration.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/configuration.html Wed Jan 16 22:39:43 2008 +0100
@@ -0,0 +1,1027 @@
+
+
+
+
+Vmailmgr Configuration Files
+
+
+Vmailmgr Configuration Files
+14 September 2000
+Bruce Guenter
+
+
+
Table of Contents
+
+
+
+
+
+
+
+
+
+
+
+The system will look for the configuration files listed below in one of
+the following three locations, in the order they are listed:
+
+
+- The domain-local configuration directory
+
+
- The user-local configuration directory
+
+
- 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.
+
+
+
+
+
+
+
+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.
+
+
+
+
+
+
+
+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).
+
+
+
+
+
+
+
+Each of the following sections identifies a single configuration file
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- Type
+
-
+executable
+
- Default
+
-
+@samp {vpopbull}
+
- Used By
+
-
+authvmailmgr
+
- Description
+
-
+This is executed by authvmailmgr after a user is successfully authenticated.
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- Type
+
-
+string
+
- Default
+
-
+`message.txt'
+
- Used By
+
-
+vmailmgrd, autoresponder script
+
- Description
+
-
+Identifies the file name within the autoresponse directory that contains
+the autoresponse message.
+
+
+
+
+
+
+
+
+- Type
+
-
+directory
+
- Default
+
-
+`bulletins'
+
- Used By
+
-
+checkvpw
+
- Description
+
-
+Identifies the subdirectory of the domain directory in which bulletins
+local to a domain are stored.
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- Type
+
-
+executable
+
- Default
+
-
+Empty
+
- Used By
+
-
+checkvpw
+
- Description
+
-
+This is executed by checkvpw after the subcommand successfully completes.
+
+
+
+
+
+
+
+
+- Type
+
-
+executable
+
- Default
+
-
+@samp {vpopbull}
+
- Used By
+
-
+checkvpw
+
- Description
+
-
+This is executed by checkvpw after a user is successfully authenticated.
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- Type
+
-
+number
+
- Default
+
-
+`-1'
+
- Used By
+
-
+vadduser
+
- Description
+
-
+Sets the default expiry value for newly created users.
+Negative values indicate no expiry.
+
+
+
+
+
+
+
+
+- Type
+
-
+directory
+
- Default
+
-
+`Maildir'
+
- Used By
+
-
+checkvpw
+
- Description
+
-
+Sets the name of the directory to be used as a non-virtual user's maildir.
+
+
+
+
+
+
+
+
+- Type
+
-
+number
+
- Default
+
-
+`-1'
+
- Used By
+
-
+vadduser
+
- Description
+
-
+Sets the default message count limit.
+
+
+
+
+
+
+
+
+- Type
+
-
+number
+
- Default
+
-
+`-1'
+
- Used By
+
-
+vadduser
+
- Description
+
-
+Sets the default message size limit, in bytes.
+
+
+
+
+
+
+
+
+- Type
+
-
+number
+
- Default
+
-
+`-1'
+
- Used By
+
-
+vadduser
+
- Description
+
-
+Sets the default hard quota, in bytes.
+
+
+
+
+
+
+
+
+- Type
+
-
+number
+
- Default
+
-
+`-1'
+
- Used By
+
-
+vadduser
+
- Description
+
-
+Sets the default soft quota, in bytes.
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- Type
+
-
+directory
+
- Default
+
-
+`/var/spool/bulletins'
+
- Used By
+
-
+checkvpw
+
- Description
+
-
+Identifies a site-wide bulletin directory.
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- 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'.
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- Type
+
-
+
- Default
+
-
+`0'
+
- Used By
+
-
+vmailmgrd and command-line programs when creating new users.
+
- Description
+
-
+See section 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/'.
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- 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.
+
+
+
+
+
+
+
+
+- Type
+
-
+executable
+
- Default
+
-
+Empty
+
- Used By
+
-
+vsetup
+
- Description
+
-
+This list is executed after the vsetup command has sucessfully done
+everything else.
+
+
+
+
+
+
+
+
+- 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.
+
+