diff -r 30113bfbe723 -r b3afb9f1e801 doc/configuration.html
--- a/doc/configuration.html Sun Jan 20 00:12:17 2008 +0100
+++ b/doc/configuration.html Sun Jan 20 00:22:09 2008 +0100
@@ -1,85 +1,93 @@
+
+
+
-
+Vmailmgr Configuration Files:
-Vmailmgr Configuration Files
+
+
+
+
+
+
-
-Vmailmgr Configuration Files
-14 September 2000
-Bruce Guenter
+
+
+
+
+
+Vmailmgr Configuration Files
+
+
-
-
Table of Contents
-
-
+
+
+
+
+
+ 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:
-
- 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
@@ -88,79 +96,112 @@
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
@@ -172,101 +213,160 @@
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.
+
- The home directory of the real user.
- `MAILDIR'
-
-
-The mail directory of the real or virtual user.
+
- The mail directory of the real or virtual user.
- `USER'
-
-
-The real user's name.
+
- The real user's name.
- `VUSER'
-
-
-The virtual user's name.
+
- 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).
+
- The virtual user's creation time (or "0" if unknown).
- `VUSER_EXPIRY'
-
-
-The virtual user's expiry time (or "-" if not applicable).
+
- 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).
+
- 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).
+
- The virtual user's message count limit (or "-" if not applicable).
- `VUSER_MSGSIZE'
-
-
-The virtual user's message size limit (or "-" if not applicable).
+
- The virtual user's message size limit (or "-" if not applicable).
- `VUSER_PERSONAL'
-
-
-The virtual user's personal data.
+
- The virtual user's personal data.
- `VUSER_SOFTQUOTA'
-
-
-The virtual user's total size soft quota (in bytes, or "-" if not applicable).
+
- 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
+
-
-
+
-Each of the following sections identifies a single configuration file
-
-
-
-
+
+
+
+
+ 2.1 authvmailmgr-error
+
+
-
- Type
-
-
-executable
+
- executable
- Default
-
-
-Empty
+
- Empty
- Used By
-
-
-authvmailmgr
+
- authvmailmgr
- Description
-
-
-This is executed by authvmailmgr if any error occurrs other than those
+
- 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
+
- executable
- Default
-
-
-Empty
+
- Empty
- Used By
-
-
-authvmailmgr
+
- authvmailmgr
- Description
-
-
-This is executed by authvmailmgr if the user's login fails.
+
- 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
@@ -274,45 +374,65 @@
This can be used to output logging messages about login failures or to
throttle hackers.
-
+
-
-
+
+
+
+
+ 2.3 authvmailmgr-postsetuid
+
+
-
- Type
-
-
-executable
+
- executable
- Default
-
-
-@samp {vpopbull}
+
- `vpopbull'
- Used By
-
-
-authvmailmgr
+
- authvmailmgr
- Description
-
-
-This is executed by authvmailmgr after a user is successfully authenticated.
+
- This is executed by authvmailmgr after a user is successfully authenticated.
+
-
-
-
+
+
+
+
+ 2.4 authvmailmgr-presetuid
+
+
-
- Type
-
-
-executable
+
- executable
- Default
-
-
-Empty
+
- Empty
- Used By
-
-
-authvmailmgr
+
- authvmailmgr
- Description
-
-
-This list is executed by authvmailmgr before changing user away from root,
+
- 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
@@ -320,112 +440,162 @@
For the same reason, `VUSER' is not authenticated and is under
complete control of the invoking user.
-
+
-
-
+
+
+
+
+ 2.5 autoresponse-dir
+
+
-
- Type
-
-
-directory
+
- directory
- Default
-
-
-`autoresponse'
+
- `autoresponse'
- Used By
-
-
-vmailmgrd, autoresponder script
+
- vmailmgrd, autoresponder script
- Description
-
-
-Identifies the subdirectory of the virtual user directory in which all
+
- Identifies the subdirectory of the virtual user directory in which all
autoresponse data is stored.
-
+
-
-
+
+
+
+
+ 2.6 autoresponse-file
+
+
-
- Type
-
-
-string
+
- string
- Default
-
-
-`message.txt'
+
- `message.txt'
- Used By
-
-
-vmailmgrd, autoresponder script
+
- vmailmgrd, autoresponder script
- Description
-
-
-Identifies the file name within the autoresponse directory that contains
+
- Identifies the file name within the autoresponse directory that contains
the autoresponse message.
-
+
-
-
+
+
+
+
+ 2.7 bulletin-dir
+
+
-
- Type
-
-
-directory
+
- directory
- Default
-
-
-`bulletins'
+
- `bulletins'
- Used By
-
-
-checkvpw
+
- checkvpw
- Description
-
-
-Identifies the subdirectory of the domain directory in which bulletins
+
- Identifies the subdirectory of the domain directory in which bulletins
local to a domain are stored.
-
+
-
-
+
+
+
+
+ 2.8 checkvpw-error
+
+
-
- Type
-
-
-executable
+
- executable
- Default
-
-
-Empty
+
- Empty
- Used By
-
-
-checkvpw
+
- checkvpw
- Description
-
-
-This is executed by checkvpw if any error occurrs other than those
+
- 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
+
- executable
- Default
-
-
-Empty
+
- Empty
- Used By
-
-
-checkvpw
+
- checkvpw
- Description
-
-
-This is executed by checkvpw if the user's login fails.
+
- 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
@@ -433,65 +603,95 @@
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.
-
-
-
-
-
+
+
+
+
+ 2.10 checkvpw-postexec
+
+
-
- Type
-
-
-executable
+
- executable
- Default
-
-
-@samp {vpopbull}
+
- Empty
- Used By
-
-
-checkvpw
+
- checkvpw
- Description
-
-
-This is executed by checkvpw after a user is successfully authenticated.
+
- This is executed by checkvpw after the subcommand successfully completes.
+
-
-
-
+
+
+
+
+ 2.11 checkvpw-postsetuid
+
+
-
- Type
-
-
-executable
+
- executable
- Default
-
-
-Empty
+
- `vpopbull'
- Used By
-
-
-checkvpw
+
- checkvpw
- Description
-
-
-This list is executed by checkvpw before changing user away from root,
+
- 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
@@ -499,279 +699,409 @@
For the same reason, `VUSER' is not authenticated and is under
complete control of the invoking user.
-
+
-
-
+
+
+
+
+ 2.13 default-expiry
+
+
-
- Type
-
-
-number
+
- number
- Default
-
-
-`-1'
+
- `-1'
- Used By
-
-
-vadduser
+
- vadduser
- Description
-
-
-Sets the default expiry value for newly created users.
+
- Sets the default expiry value for newly created users.
Negative values indicate no expiry.
-
+
-
-
+
+
+
+
+ 2.14 default-maildir
+
+
-
- Type
-
-
-directory
+
- directory
- Default
-
-
-`Maildir'
+
- `Maildir'
- Used By
-
-
-checkvpw
+
- checkvpw
- Description
-
-
-Sets the name of the directory to be used as a non-virtual user's maildir.
+
- Sets the name of the directory to be used as a non-virtual user's maildir.
+
-
-
-
+
+
+
+
+ 2.15 default-msgcount
+
+
-
- Type
-
-
-number
+
- number
- Default
-
-
-`-1'
+
- `-1'
- Used By
-
-
-vadduser
+
- vadduser
- Description
-
-
-Sets the default message count limit.
+
- Sets the default message count limit.
+
-
-
-
+
+
+
+
+ 2.16 default-msgsize
+
+
-
- Type
-
-
-number
+
- number
- Default
-
-
-`-1'
+
- `-1'
- Used By
-
-
-vadduser
+
- vadduser
- Description
-
-
-Sets the default message size limit, in bytes.
+
- Sets the default message size limit, in bytes.
+
-
-
-
+
+
+
+
+ 2.17 default-hardquota
+
+
-
- Type
-
-
-number
+
- number
- Default
-
-
-`-1'
+
- `-1'
- Used By
-
-
-vadduser
+
- vadduser
- Description
-
-
-Sets the default hard quota, in bytes.
+
- Sets the default hard quota, in bytes.
+
-
-
-
+
+
+
+
+ 2.18 default-softquota
+
+
-
- Type
-
-
-number
+
- number
- Default
-
-
-`-1'
+
- `-1'
- Used By
-
-
-vadduser
+
- vadduser
- Description
-
-
-Sets the default soft quota, in bytes.
+
- Sets the default soft quota, in bytes.
+
-
-
-
+
+
+
+
+ 2.19 default-username
+
+
-
- Type
-
-
-string
+
- string
- Default
-
-
-`+'
+
- `+'
- Used By
-
-
-vmailmgrd
+
- vmailmgrd
- Description
-
-
-Identifies the name of the virtual user to be looked up if a lookup of
+
- 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
+
- directory
- Default
-
-
-`/var/lib/vmailmgr/error-maildir'
+
- `/var/lib/vmailmgr/error-maildir'
- Used By
-
-
-checkvpw
+
- checkvpw
- Description
-
-
-Specifies the path of a read-only maildir containing a message to be
+
- 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.
-
-
-
-
-
+
+
+
+
+ 2.21 global-bulletin-dir
+
+
-
- Type
-
-
-string
+
- directory
- Default
-
-
-`maildir'
+
- `/var/spool/bulletins'
- Used By
-
-
-checkvpw (global only)
+
- checkvpw
- Description
-
-
-Identifies the string to search for when attempting to identify the
+
- 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
+
- string
- Default
-
-
-`passwd'
+
- `passwd'
- Used By
-
-
-vmailmgrd and command-line programs
+
- vmailmgrd and command-line programs
- Description
-
-
-Identifies the file that contains user names, passwords, and
+
- 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
+
- list
- Default
-
-
-`mailer-daemon'
+
- `mailer-daemon'
`postmaster'
`root'
- Used By
-
-
-vsetup
+
- vsetup
- Description
-
-
-A list of aliases to the postmaster email address to set
+
- 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
+
- string
- Default
-
-
-`postmaster@'
+
- `postmaster@'
- Used By
-
-
-vsetup
+
- vsetup
- Description
-
-
-Identifies the email address of the entity responsible
+
- 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
@@ -781,247 +1111,626 @@
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
+
- string
- Default
-
-
-`/var/qmail'
+
- `/var/qmail'
- Used By
-
-
-checkvpw, vdeliver, vmailmgrd
+
- checkvpw, vdeliver, vmailmgrd
- Description
-
-
-Specifies the location of the base directory of your qmail install.
+
- 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
+
- string
- Default
-
-
-`@:'
+
- `@:'
- Used By
-
-
-checkvpw (global only)
+
- checkvpw (global only)
- Description
-
-
-Identifies the set of valid separators within a user login name between
+
- 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
+
- string
- Default
-
-
-`/tmp/.vmailmgrd'
+
- `/tmp/.vmailmgrd'
- Used By
-
-
-vmailmgrd, checkvpw, vdeliver, and the CGI programs
+
- vmailmgrd, checkvpw, vdeliver, and the CGI programs
- Description
-
-
-Identifies the file name of the local socket used to
+
- 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
+
- directory
- Default
-
-
-`users'
+
- `users'
- Used By
-
-
-vmailmgrd and command-line programs
+
- vmailmgrd and command-line programs
- Description
-
-
-Identifies the subdirectory from the virtual domain directory in which a
+
- 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'
+
- Default
+
- `0'
- Used By
-
-
-vmailmgrd and command-line programs when creating new users.
+
- vmailmgrd and command-line programs when creating new users.
- Description
-
-
-See section 2.31 user-dir-slices
+
- See section 2.31 user-dir-slices.
+
-
-
-
+
+
+
+
+ 2.31 user-dir-slices
+
+
-
- Type
-
-
-
- Default
-
-
-`0'
+
- Default
+
- `0'
- Used By
-
-
-vmailmgrd and command-line programs when creating new users.
+
- vmailmgrd and command-line programs when creating new users.
- Description
-
-
-`user-dir-bits' and `user-dir-slices' work together. When creating a
+
- `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
+
- executable
- Default
-
-
-Empty
+
- Empty
- Used By
-
-
-vdeliver
+
- vdeliver
- Description
-
-
-This list is executed after the delivery is successfully
+
- 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
+
- executable
- Default
-
-
-Empty
+
- Empty
- Used By
-
-
-vdeliver
+
- vdeliver
- Description
-
-
-This list is executed before the delivery is attempted, but
+
- 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
+
- executable
- Default
-
-
-Empty
+
- Empty
- Used By
-
-
-vsetup
+
- vsetup
- Description
-
-
-This list is executed after the vsetup command has sucessfully done
+
- This list is executed after the vsetup command has sucessfully done
everything else.
-
+
-
-
+
+
+
+
+ 2.35 vsetup-pre
+
+
-
- Type
-
-
-executable
+
- executable
- Default
-
-
-Empty
+
- Empty
- Used By
-
-
-vsetup
+
- vsetup
- Description
-
-
-This list is executed before the vsetup command makes any changes.
+
- This list is executed before the vsetup command makes any changes.
+
+
+
+
+
+Table of Contents
+
+
+
+
+Short Table of Contents
+
+1. General Information
+
+2. Configuration Files
+
-
-This document was generated on 14 September 2000 using
-texi2html 1.56k.
+
+
+
+
+About this document
+This document was generated by Bruce.Guenter.dyndns.org on December, 29 2004
+using texi2html
+
+The buttons in the navigation panels have the following meaning:
+
+
+
+| Button |
+ Name |
+ Go to |
+ From 1.2.3 go to |
+
+
+|
+ [ < ] |
+
+Back
+ |
+
+previous section in reading order
+ |
+
+1.2.2
+ |
+
+
+|
+ [ > ] |
+
+Forward
+ |
+
+next section in reading order
+ |
+
+1.2.4
+ |
+
+
+|
+ [ << ] |
+
+FastBack
+ |
+
+previous or up-and-previous section
+ |
+
+1.1
+ |
+
+
+|
+ [ Up ] |
+
+Up
+ |
+
+up section
+ |
+
+1.2
+ |
+
+
+|
+ [ >> ] |
+
+FastForward
+ |
+
+next or up-and-next section
+ |
+
+1.3
+ |
+
+
+|
+ [Top] |
+
+Top
+ |
+
+cover (top) of document
+ |
+
+
+ |
+
+
+|
+ [Contents] |
+
+Contents
+ |
+
+table of contents
+ |
+
+
+ |
+
+
+|
+ [Index] |
+
+Index
+ |
+
+concept index
+ |
+
+
+ |
+
+
+|
+ [ ? ] |
+
+About
+ |
+
+this page
+ |
+
+
+ |
+
+
+
+where the Example assumes that the current position
+is at Subsubsection One-Two-Three of a document of
+the following structure:
+
+- 1. Section One
+
+- 1.1 Subsection One-One
+
+- 1.2 Subsection One-Two
+
+- 1.2.1 Subsubsection One-Two-One
+
- 1.2.2 Subsubsection One-Two-Two
+
- 1.2.3 Subsubsection One-Two-Three
+<== Current Position
+
- 1.2.4 Subsubsection One-Two-Four
+
+- 1.3 Subsection One-Three
+
+- 1.4 Subsection One-Four
+
+
+
+
+
+
+This document was generated
+by Bruce.Guenter.dyndns.org on December, 29 2004
+using texi2html
+