6.2 Mailutils

This module uses GNU Mailutils (http://www.gnu.org/software/mailutils) and provides two main modes:

auth

This mode uses GNU Mailutils authorization mechanism to obtain user data (similar to the system ‘getpwnam’ routine) and returns positive reply if the data were retrieved and negative reply otherwise. See section Example: Using smapd with MeTA1, for an example on how to use it as a local user and alias database.

mbq

This mode allows to check whether the user's mailbox exceeded the allotted quota, and if not, whether it is able to accept a message of the given size without exceeding it. The mode name is an abbreviation of Mailbox Quota.

6.2.1 Variable Expansion

In the discussion below we often refer to meta-variable expansion in strings. This is a process, whereby any sequence ‘${variable}’ is replaced with the value of variable. The defined variables are:

db

The database name.

map

The map name.

key

The lookup key.

diag

If the key was not found or some error occurred, this variable expands to a short diagnostics string, suitable for return message. Otherwise, expands to empty string.

name

The ‘name’ field from the retrieved record. Empty string if the user not found.

passwd

The ‘passwd’ field from the retrieved record. Empty string if the user not found.

uid

The ‘uid’ field from the retrieved record. If the user was not found, expands to ‘-1’.

gid

The ‘gid’ field from the retrieved record. If the user was not found, expands to ‘-1’.

gecos

The ‘gecos’ field from the retrieved record. Empty string if the user not found.

dir

The ‘dir’ field from the retrieved record. Empty string if the user not found.

shell

The ‘shell’ field from the retrieved record. Empty string if the user not found.

mailbox

The ‘mailbox’ field from the retrieved record. Empty string if the user not found.

quota

The ‘quota’ field from the retrieved record. If the user was not found, expands to ‘NONE’.

mbsize

Mailbox size, in bytes. Defined only in ‘mbq’ mode.

msgsize

Expected message size, in bytes. Defined only in ‘mbq’ mode.

6.2.2 Mailutils Loading Sequence

 
module mailutils mailutils [args]

Arguments are:

config-verbose

Verbosely trace the processing of the main Mailutils configuration files.

config-dump

Dump the parse tree from the Mailutils configuration.

positive-reply=str

Declare default positive reply string. This string is returned when the underlying database was able to found the requested key. Prior to returning, str is subject to meta-variable expansion, as described above.

Default positive reply string is ‘OK’.

negative-reply=str

Declare default negative reply string. This string is returned when the underlying database failed to found the requested key. Prior to returning, str is subject to meta-variable expansion.

Default negative reply string is ‘NOTFOUND’.

onerror-reply=str

Declare a reply to be returned on error. Prior to returning, str is subject to meta-variable expansion. Default string is ‘NOTFOUND’.

The module reads most of its configuration settings from the main Mailutils configuration file. See Mailutils Configuration File: (mailutils)configuration section `configuration' in GNU Mailutils Manual, for a description of GNU Mailutils configuration system. It looks for smap-specific settings in the section ‘program smap-mailutils’.

Statement Reference
server See Mailutils Configuration File: (mailutils)Server Settings section `Server Settings' in GNU Mailutils Manual.
auth See Mailutils Configuration File: (mailutils)Auth Statement section `Auth Statement' in GNU Mailutils Manual.
pam See Mailutils Configuration File: (mailutils)PAM Statement section `PAM Statement' in GNU Mailutils Manual.
virtdomain See Mailutils Configuration File: (mailutils)Virtdomain Statement section `Virtdomain Statement' in GNU Mailutils Manual.
radius See Mailutils Configuration File: (mailutils)Radius Statement section `Radius Statement' in GNU Mailutils Manual.
sql See Mailutils Configuration File: (mailutils)SQL Statement section `SQL Statement' in GNU Mailutils Manual.
ldap See Mailutils Configuration File: (mailutils)LDAP Statement section `LDAP Statement' in GNU Mailutils Manual.
debug See Mailutils Configuration File: (mailutils)Debug Statement section `Debug Statement' in GNU Mailutils Manual.
logging See Mailutils Configuration File: (mailutils)Logging Statement section `Logging Statement' in GNU Mailutils Manual.
include See Mailutils Configuration File: (mailutils)Include section `Include' in GNU Mailutils Manual.

The module uses GNU Mailutils authorization databases to obtain the requested data. This concept is described in detail in Mailutils Configuration File: (mailutils)Auth Statement section `Auth Statement' in GNU Mailutils Manual.

6.2.3 Mailutils Databases

Mailutils databases are normally declared as follows:

 
database name mailutils mode=mode [args]

Here, name is the database name, mode is ‘auth’ if the database should work in auth mode, and ‘mbq’ if it should run in mbq mode. If the ‘mode’ argument is omitted, ‘auth’ is assumed. Optional args may be used to supply additional database configuration. These are:

positive-reply=str

Declare positive reply string. This string is returned when the underlying database was able to found the requested key. Prior to returning, str is subject to meta-variable expansion, as described above.

Default positive reply string is ‘OK’, unless overridden by the module-level ‘positive-reply’ option (see section positive-reply.

negative-reply=str

Declare negative reply string. This string is returned when the underlying database failed to found the requested key. Prior to returning, str is subject to meta-variable expansion.

Default negative reply string is ‘NOTFOUND’, unless overridden by the module-level ‘positive-reply’ option (see section negative-reply.

onerror-reply=str

Declare a reply to be returned on error. Prior to returning, str is subject to meta-variable expansion. Default string is ‘NOTFOUND’, unless overridden by the module-level ‘positive-reply’ option (see section onerr-reply.

6.2.4 Mailutils Auth Mode

Mailutils module in ‘auth’ mode uses GNU Mailutils authorization mechanism to obtain user data. It returns ‘positive-reply’ if the data were retrieved and ‘negative-reply’ otherwise. This mode is often used for databases of local users and aliases. The key is normally a user name (either local part or fully qualified).

See section Example: Using smapd with MeTA1, for an example on how to use it.

6.2.5 Mailutils MBQ Mode

MBQ, or Mailbox Quota mode, uses key as the name of a local user. It obtains the user parameters via Mailutils authorization mechanism and then switches to this user privileges and opens his mailbox for a brief period of time. After opening it determines the mailbox size and closes it. The mode returns ‘positive-reply’ if the mailbox size is less than the quota, and ‘netagive-reply’ otherwise.

If the key value consists of two words, separated by whitespace, then the first word is used as a user name, and the second one as a size of a message which is about to be delivered to that user's mailbox (the size may be optionally prefixed by ‘SIZE=’). In this case, ‘positive-reply’ is returned if the actual mailbox size plus the message size is less than quota.

Two additional meta-variables may be used in reply templates to return quota-related information:

mbsize

Mailbox size, in bytes. Defined only in ‘mbq’ mode.

msgsize

Expected message size, in bytes. Defined only in ‘mbq’ mode.

The following example shows a definition of ‘mbq’ database which the author uses on his servers:

 
database mbq mailutils mode=mbq \
  positive-reply="OK [${diag}] ${mailbox} ${mbsize} ${quota}"\
  negative-reply="NOTFOUND [${diag}] ${mailbox} ${mbsize} ${quota}"\
  onerror-reply="NOTFOUND [${diag}]"

The ‘diag’ meta-variable contains a diagnostic string suitable for passing it back to the MTA. For example, in the case of ‘negative-reply’, ‘${diag}’ expands to:

 
mailbox quota exceeded for this recipient

if the mailbox has grown beyond the allowed quota, and

 
message would exceed maximum mailbox size for this recipient

if message of the given size cannot be delivered to mailbox without violating its quota.

Notice, that this mode requires superuser privileges.