# Vmailmgr Configuration Files

## 14 September 2000

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