\input texinfo @c -*-texinfo-*-

@c %**start of header

@setfilename configuration.info

@settitle Vmailmgr Configuration Files

@setchapternewpage off

@paragraphindent 5

@footnotestyle end

@c %**end of header

@ifinfo

Copyright @copyright{} 1998 Bruce Guenter

@end ifinfo

@titlepage

@title Vmailmgr Configuration Files

@author Bruce Guenter

@subtitle @today{}

@end titlepage

@node Top, General Information, (dir), (dir)

@menu

* General Information::         

* Configuration Files::         

@end menu

@c ****************************************************************************

@node General Information, Configuration Files, Top, Top

@chapter General Information

@menu

* Search Order::                

* File Types::                  

* Command Execution::           

@end menu

@c ============================================================================

@node Search Order, File Types, General Information, General Information

@section 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:

@enumerate

@item The domain-local configuration directory

@item The user-local configuration directory

@item The global configuration directory

@end enumerate

The global configuration directory is set to @file{/etc/vmailmgr} by

default.

The user-local and domain-local configuration directories (for now, one

and the same) are a subdirectory, named @file{.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.

@c ============================================================================

@node File Types, Command Execution, Search Order, General Information

@section File Types

Each of the configuration files falls into one of the following types:

@table @asis

@item String

A single line is read from this type and used as-is with no conversion.

All data after the first line is ignored.

@item Directory

A single line is read from this type.

If it does not have a trailing slash (@samp{/}), one is appended.

All data after the first line is ignored.

@item 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.

@item 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 (@samp{#}) are ignored.

@item 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.

@end table

All lines are stripped of any leading or trailing white space.

Configuration files marked as @samp{(global only)} are read

before any user-level processing occurrs, and so are not functional in

the user-level configuration.

@c ============================================================================

@node Command Execution,  , File Types, General Information

@section 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 @samp{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 @file{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 @file{qmail-command} man page for full details on delivery error

codes.

For @file{checkvpw}, any non-zero exit code (except as described above)

will cause authentication to fail.

The following environment variables will be set (where applicable):

@table @samp

@item HOME

The home directory of the real user.

@item MAILDIR

The mail directory of the real or virtual user.

@item USER

The real user's name.

@item VUSER

The virtual user's name.

For base user logins, this is blank, and all the following items

prefixed with @samp{VUSER_} are not set.

@item VUSER_CTIME

The virtual user's creation time (or "0" if unknown).

@item VUSER_EXPIRY

The virtual user's expiry time (or "-" if not applicable).

@item VUSER_HARDQUOTA

The virtual user's total size hard quota (in bytes, or "-" if not applicable).

@item VUSER_MSGCOUNT

The virtual user's message count limit (or "-" if not applicable).

@item VUSER_MSGSIZE

The virtual user's message size limit (or "-" if not applicable).

@item VUSER_PERSONAL

The virtual user's personal data.

@item VUSER_SOFTQUOTA

The virtual user's total size soft quota (in bytes, or "-" if not applicable).

@end table

@c ****************************************************************************

@node Configuration Files,  , General Information, Top

@chapter Configuration Files

Each of the following sections identifies a single configuration file

@menu

* authvmailmgr-error::          

* authvmailmgr-loginfail::      

* authvmailmgr-postsetuid::     

* authvmailmgr-presetuid::      

* autoresponse-dir::            

* autoresponse-file::           

* bulletin-dir::                

* checkvpw-error::              

* checkvpw-loginfail::          

* checkvpw-postexec::           

* checkvpw-postsetuid::         

* checkvpw-presetuid::          

* default-expiry::              

* default-maildir::             

* default-msgcount::            

* default-msgsize::             

* default-hardquota::           

* default-softquota::           

* default-username::            

* error-maildir::               

* global-bulletin-dir::         

* maildir-arg-str::             

* password-file::               

* postmaster-aliases::          

* postmaster-email::            

* qmail-root::                  

* separators::                  

* socket-file::                 

* user-dir::                    

* user-dir-bits::               

* user-dir-slices::             

* vdeliver-postdeliver::        

* vdeliver-predeliver::         

* vsetup-post::                 

* vsetup-pre::                  

@end menu

@c ============================================================================

@node authvmailmgr-error, authvmailmgr-loginfail, Configuration Files, Configuration Files

@section authvmailmgr-error

@table @strong

@item Type

executable

@item Default

Empty

@item Used By

authvmailmgr

@item Description

This is executed by authvmailmgr if any error occurrs other than those

caught by @file{authvmailmgr-loginfail} below.

The environment variable @code{AUTHVMAILMGR_ERROR} will contain an error

message.

This can be used to output logging messages about errors in authvmailmgr.

@end table

@c ============================================================================

@node authvmailmgr-loginfail, authvmailmgr-postsetuid, authvmailmgr-error, Configuration Files

@section authvmailmgr-loginfail

@table @strong

@item Type

executable

@item Default

Empty

@item Used By

authvmailmgr

@item Description

This is executed by authvmailmgr if the user's login fails.

The environment variable @code{AUTHVMAILMGR_ERROR} will contain an error

message.

The environment variable @code{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.

@end table

@c ============================================================================

@node authvmailmgr-postsetuid, authvmailmgr-presetuid, authvmailmgr-loginfail, Configuration Files

@section authvmailmgr-postsetuid

@table @strong

@item Type

executable

@item Default

@samp {vpopbull}

@item Used By

authvmailmgr

@item Description

This is executed by authvmailmgr after a user is successfully authenticated.

@end table

@c ============================================================================

@node authvmailmgr-presetuid, autoresponse-dir, authvmailmgr-postsetuid, Configuration Files

@section authvmailmgr-presetuid

@table @strong

@item Type

executable

@item Default

Empty

@item Used By

authvmailmgr

@item Description

This list is executed by authvmailmgr before changing user away from root,

and before authenticating a virtual user.

Note: The environment variable @samp{MAILDIR} is not set since the

virtual user has not yet been authenticated, or even looked up

at this point.

For the same reason, @samp{VUSER} is not authenticated and is under

complete control of the invoking user.

@end table

@c ============================================================================

@node autoresponse-dir, autoresponse-file, authvmailmgr-presetuid, Configuration Files

@section autoresponse-dir

@table @strong

@item Type

directory

@item Default

@samp{autoresponse}

@item Used By

vmailmgrd, autoresponder script

@item Description

Identifies the subdirectory of the virtual user directory in which all

autoresponse data is stored.

@end table

@c ============================================================================

@node autoresponse-file, bulletin-dir, autoresponse-dir, Configuration Files

@section autoresponse-file

@table @strong

@item Type

string

@item Default

@samp{message.txt}

@item Used By

vmailmgrd, autoresponder script

@item Description

Identifies the file name within the autoresponse directory that contains

the autoresponse message.

@end table

@c ============================================================================

@node bulletin-dir, checkvpw-error, autoresponse-file, Configuration Files

@section bulletin-dir

@table @strong

@item Type

directory

@item Default

@samp{bulletins}

@item Used By

checkvpw

@item Description

Identifies the subdirectory of the domain directory in which bulletins

local to a domain are stored.

@end table

@c ============================================================================

@node checkvpw-error, checkvpw-loginfail, bulletin-dir, Configuration Files

@section checkvpw-error

@table @strong

@item Type

executable

@item Default

Empty

@item Used By

checkvpw

@item Description

This is executed by checkvpw if any error occurrs other than those

caught by @file{checkvpw-loginfail} below.

The environment variable @code{CHECKVPW_ERROR} will contain an error

message.

This can be used to output logging messages about errors in checkvpw.

@end table

@c ============================================================================

@node checkvpw-loginfail, checkvpw-postexec, checkvpw-error, Configuration Files

@section checkvpw-loginfail

@table @strong

@item Type

executable

@item Default

Empty

@item Used By

checkvpw

@item Description

This is executed by checkvpw if the user's login fails.

The environment variable @code{CHECKVPW_ERROR} will contain an error

message.

The environment variable @code{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.

@end table

@c ============================================================================

@node checkvpw-postexec, checkvpw-postsetuid, checkvpw-loginfail, Configuration Files

@section checkvpw-postexec

@table @strong

@item Type

executable

@item Default

Empty

@item Used By

checkvpw

@item Description

This is executed by checkvpw after the subcommand successfully completes.

@end table

@c ============================================================================

@node checkvpw-postsetuid, checkvpw-presetuid, checkvpw-postexec, Configuration Files

@section checkvpw-postsetuid

@table @strong

@item Type

executable

@item Default

@samp {vpopbull}

@item Used By

checkvpw

@item Description

This is executed by checkvpw after a user is successfully authenticated.

@end table

@c ============================================================================

@node checkvpw-presetuid, default-expiry, checkvpw-postsetuid, Configuration Files

@section checkvpw-presetuid

@table @strong

@item Type

executable

@item Default

Empty

@item Used By

checkvpw

@item Description

This list is executed by checkvpw before changing user away from root,

and before authenticating a virtual user.

Note: The environment variable @samp{MAILDIR} is not set since the

virtual user has not yet been authenticated, or even looked up

at this point.

For the same reason, @samp{VUSER} is not authenticated and is under

complete control of the invoking user.

@end table

@c ============================================================================

@node  default-expiry, default-maildir, checkvpw-presetuid, Configuration Files

@section default-expiry

@table @strong

@item Type

number

@item Default

@samp{-1}

@item Used By

vadduser

@item Description

Sets the default expiry value for newly created users.

Negative values indicate no expiry.

@end table

@c ============================================================================

@node  default-maildir, default-msgcount, default-expiry, Configuration Files

@section default-maildir

@table @strong

@item Type

directory

@item Default

@samp{Maildir}

@item Used By

checkvpw

@item Description

Sets the name of the directory to be used as a non-virtual user's maildir.

@end table

@c ============================================================================

@node  default-msgcount, default-msgsize, default-maildir, Configuration Files

@section default-msgcount

@table @strong

@item Type

number

@item Default

@samp{-1}

@item Used By

vadduser

@item Description

Sets the default message count limit.

@end table

@c ============================================================================

@node  default-msgsize, default-hardquota, default-msgcount, Configuration Files

@section default-msgsize

@table @strong

@item Type

number

@item Default

@samp{-1}

@item Used By

vadduser

@item Description

Sets the default message size limit, in bytes.

@end table

@c ============================================================================

@node default-hardquota, default-softquota, default-msgsize, Configuration Files

@section default-hardquota

@table @strong

@item Type

number

@item Default

@samp{-1}

@item Used By

vadduser

@item Description

Sets the default hard quota, in bytes.

@end table

@c ============================================================================

@node default-softquota, default-username, default-hardquota, Configuration Files

@section default-softquota

@table @strong

@item Type

number

@item Default

@samp{-1}

@item Used By

vadduser

@item Description

Sets the default soft quota, in bytes.

@end table

@c ============================================================================

@node default-username, error-maildir, default-softquota, Configuration Files

@section default-username

@table @strong

@item Type

string

@item Default

@samp{+}

@item Used By

vmailmgrd

@item Description

Identifies the name of the virtual user to be looked up if a lookup of

another virtual user fails.

@end table

@c ============================================================================

@node error-maildir, global-bulletin-dir, default-username, Configuration Files

@section error-maildir

@table @strong

@item Type