This edition of the GNU Mailutils Manual, last updated on 26 December 2008, documents GNU Mailutils Version 2.0.
Appendices
Indices
--- The Detailed Node Listing ---
Introduction
Mailutils Programs
Command Line
Mailutils Configuration File
Configuration File Syntax
Server Settings
mail --- Send and Receive Mail
Composing Mail
Reading Mail
movemail --- Moves Mail from the User Maildrop to the Local File
readmsg --- Extract Messages from a Folder
sieve
A Sieve Interpreter
guimb --- A Mailbox Scanning and Processing Language
maidag
Mailbox Quotas
Maidag Scripting
mail.local --- Deliver Mail to the Local UNIX Mailbox
mimeview
POP3 Daemon
IMAP4 Daemon
Comsat Daemon
Configuring comsatd
MH --- The MH Message Handling System
Major differences between Mailutils MH and other MH implementations
mailutils-config --- Get the Information about the Mailutils Build
Mailutils Libraries
Framework
Authentication Library
Mailutils to Scheme Interface
Using libmu_scm
Sieve Library
Sieve Language
Syntax
Preprocessor
Tests
Actions
Date Input Formats
GNU Mailutils contains a series of useful mail clients, servers, and libraries. These are the primary mail utilities of the GNU system. Specifically, this package contains a POP3 server, an IMAP4 server, and a Sieve mail filter. It also provides a POSIX `mailx' client, and a collection of other tools. All utilities can manipulate the mailboxes of various formats, both local, stored on the hard disk, and remote, accessed via network protocols, such as POP3 or IMAP4.
The GNU Mailutils libraries supply a rich set of primitives for handling electronic mail in programs written in C, C++ or Scheme.
This software is part of the GNU Project and belongs to the Free Software Foundation. All libraries are licensed using the GNU LGPL. The documentation is licensed under the GNU FDL, and everything else is licensed using the GNU GPL.
This book addresses a wide audience of both system administrators and users that aim to use Mailutils programs, and programmers who wish to use Mailutils libraries in their programs. Given this audience, the book is divided in three major parts.
The first part provides a detailed description of each Mailutils utility, and advices on how to use them in various situations. This part is intended for users and system administrators who are using Mailutils programs. If you are not interested in programming using Mailutils, this is the only part you need to read.
Subsequent parts address programmers.
The second part is a tutorial which provides an introduction to programming techniques for writing mail applications using GNU Mailutils.
Finally, the third part contains a complete Mailutils library reference.
This version of the book is not finished. The places that may contain inaccurate information carry prominent notices stating so. For updated versions of the documentation, visit http://www.gnu.org/software/mailutils/manual. If you have any questions, feel free to ask them at the mailing list bug-mailutils@gnu.org.
(The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised.)
This package started off to try and handle large mailbox files more gracefully then current POP3 servers did. While it handles this task, it also allows you to support a variety of different mailbox formats without any real effort on your part. Also, if a new format is added at a later date, your program will support that new format automatically as soon as it is compiled against the new library.
GNU Mailutils provides a broad set of utilities for handling electronic mail. These utilities address the needs of both system administrators and users.
All utilities are built around a single core subsystem and share many common aspects. All of them are able to work with almost any existing mailbox formats. They use a common configuration file syntax, and their configuration files are located in a single subdirectory.
In this chapter we will discuss each utility, and give some advices on how to use them in various real life situations.
First of all we will describe command line and configuration file syntax.
Many command line options have two forms, called short and long forms. Both forms are absolutely identical in function; they are interchangeable.
The short form is a traditional form for UNIX utilities. In this form, the option consists of a single dash, followed by a single letter, e.g. -c.
Short options which require arguments take their arguments immediately following the option letter, optionally separated by white space. For example, you might write -f name, or -fname. Here, -f is the option, and name is its argument.
Short options which allow optional arguments take their arguments immediately following the option letter, without any intervening white space characters. This is important, so that the command line parser might discern that the text following option is its argument, not the next command line parameter. For example, if option -d took an optional argument, then -dname would mean the option with its argument (name in this case), and -d name would mean the -d option without any argument, followed by command line argument name.
Short options' letters may be clumped together, but you are not required to do this. When short options are clumped as a set, use one (single) dash for them all, e.g. -cvl is equivalent to -c -v -l. However, only options that do not take arguments may be clustered this way. If an option takes an argument, it can only be the last option in such a cluster, otherwise it would be impossible to specify the argument for it. Anyway, it is much more readable to specify such options separated.
The long option names are probably easier to memorize than their short counterparts. They consist of two dashes, followed by a multi-letter option name, which is usually selected to be a mnemonics for the operation it requests. For example, --verbose is a long option that increases the verbosity of a utility. In addition, long option names can abbreviated, provided that such an abbreviation is unique among the options understood by a given utility. For example, if a utility takes options --foreground and --forward, then the shortest possible abbreviations for these options are --fore and --forw, correspondingly. If you try to use --for, the utility will abort and inform you that the abbreviation you use is ambiguous, so it is not clear which of the options you intended to use.
Long options which require arguments take those arguments following the option name. There are two ways of specifying a mandatory argument. It can be separated from the option name either by an equal sign, or by any amount of white space characters. For example, if the --file option requires an argument, and you wish to supply name as its argument, then you can do so using any of the following notations: --file=name or --file name.
In contrast, optional arguments must always be introduced using an equal sign.
All GNU Mailutils programs understand a common subset of options.
The output of this option consists of three major parts. First, a usage synopsis is displayed. For example:
Usage: sieve [OPTION...] SCRIPT
GNU sieve -- a mail filtering tool
The first line tells that the sieve utility takes any number of options (brackets indicate optional part) and a single mandatory argument (‘SCRIPT’). The second lines summarizes the purpose of the utility.
Following this header is an option summary. It consists of two columns:
-c, --compile-only Compile script and exit
-d, --debug[=FLAGS] Debug flags
-e, --email=ADDRESS Override user email address
The leftmost column contains a comma-separated list of option names. Short options are listed first. The options are ordered alphabetically. Arguments, if any, are specified after the last option name in the list, so that, e.g. the option ‘-e’ in the example above requires an argument: ‘-e ADDRESS’. Optional arguments are enclosed in square brackets, as in --debug option in the example above.
The rightmost column contains a short description of the option purpose.
The last part of --help output contains some additional notices and lists the email address for reporting bugs.
Usage: sieve [-cv?V] [--compile-only] [--debug[=FLAGS]]
[--email=ADDRESS] SCRIPT
The exact formatting of the output produced by these two options is configurable. See Usage Vars, for a detailed descriptions of it.
The following command line options affect parsing of configuration files. Here we provide a short summary, the next section will describe them in detail.
Configuration files are the principal means of configuring any GNU Mailutils component. When started, each utility tries to load its configuration from the following locations, in that order:
It is named sysconfdir/mailutils.rc, where sysconfdir stands for the system configuration directory set when compiling the package. You can obtain the value of sysconfdir by running
$ mailutils-config --info sysconfdir
or
$ prog --show-config-options | grep SYSCONFDIR
where prog stands for any GNU Mailutils utility.
The site-wide configuration file is not read if the --no-site-config command line option was given.
A per user configuration file is located in the user home directory and is named ‘.prog’, where prog is the name of the utility. For example, the per-user configuration file for sieve utility is named .sieve.
This configuration file is not read if the --no-user-config command line option was given.
The order in which configuration files are loaded defines the precedence of their settings. Thus, the settings from additional configuration file override those set in per-user configuration file. The latter, in their turn, take precedence over the settings from the site-wide configuration file.
Neither site-wide nor user configuration files are required to exist. If any or both of them are absent, GNU Mailutils does not complain, and the utility falls back to its default settings. To make configuration processing more verbose, use the --config-verbose command line option. Here is an example of what you might get using this option:
imap4d: Info: parsing file `/etc/mailutils.rc'
imap4d: Info: finished parsing file `/etc/mailutils.rc'
Specifying this option more than once adds more verbosity to this output. If this option is given two times, GNU Mailutils will print any configuration file statement it parsed, along with the exact location where it occurred (the exact meaning of each statement will be described later in this chapter):
imap4d: Info: parsing file `/etc/mailutils.rc'
# 1 "/etc/mailutils.rc"
mailbox {
# 2 "/etc/mailutils.rc"
mailbox-pattern maildir:/var/spool/mail;type=index;param=2;user=${user};
# 3 "/etc/mailutils.rc"
mailbox-type maildir;
};
# 6 "/etc/mailutils.rc"
include /etc/mailutils.d;
imap4d: Info: parsing file `/etc/mailutils.d/imap4d'
...
To test configuration file without actually starting the utility, use the --config-lint command line option. With this option, any Mailutils utility exits after finishing parsing of the configuration files. Any errors occurred during parsing are displayed on the standard error output. This option can be combined with --config-verbose to obtain more detailed output.
The --config-help command line option produces on the standard output the summary of all configuration statements understood by the utility, with detailed comments and in the form suitable for configuration file. For example, the simplest way to write a configuration file for, say, imap4d is to run
$ imap4d --config-help > imap4d.rc
and to edit the imap4d.rc file with your editor of choice.
Configuration files consist of a series of statements. Blanks, tabs, newlines and comments, collectively called white space are ignored except as they serve to separate tokens. Some white space is required to separate otherwise adjacent keywords and values.
Comments may appear anywhere where white space may appear in the configuration file. There are two kinds of comments: single-line and multi-line comments. Single-line comments start with ‘#’ or ‘//’ and continue to the end of the line:
# This is a comment
// This too is a comment
Multi-line or C-style comments start with the two characters ‘/*’ (slash, star) and continue until the first occurrence of ‘*/’ (star, slash).
Multi-line comments cannot be nested. However, single-line comments are allowed to appear within a multi-line one.
A simple statement, consists of a keyword and value separated by any amount of whitespace. Simple statement is terminated with a semicolon (‘;’), unless it contains a here-document (see below), in which case semicolon is optional.
Examples of simple statements:
pidfile /var/run/imap4d.pid;
transcript yes;
A keyword begins with a letter and may contain letters, decimal digits, underscores (‘_’) and dashes (‘-’). Examples of keywords are: ‘group’, ‘identity-check’.
A value can be one of the following:
| Sequence | Replaced with
|
| \a | Audible bell character (ASCII 7)
|
| \b | Backspace character (ASCII 8)
|
| \f | Form-feed character (ASCII 12)
|
| \n | Newline character (ASCII 10)
|
| \r | Carriage return character (ASCII 13)
|
| \t | Horizontal tabulation character (ASCII 9)
|
| \\ | A single backslash (‘\’)
|
| \" | A double-quote.
|
Table 2.1: Backslash escapes
In addition, the sequence ‘\newline’ is removed from the string. This allows to split long strings over several physical lines, e.g.:
"a long string may be\
split over several lines"
If the character following a backslash is not one of those specified above, the backslash is ignored and a warning is issued.
Two or more adjacent quoted strings are concatenated, which gives another way to split long strings over several lines to improve readability. The following fragment produces the same result as the example above:
"a long string may be"
" split over several lines"
The <<word construct instructs the parser to read all
the lines that follow up to the line containing only word, with
possible trailing blanks. Any lines thus read are concatenated
together into a single string. For example:
<<EOT
A multiline
string
EOT
Body of a here-document is interpreted the same way as double-quoted string, unless word is preceded by a backslash (e.g. ‘<<\EOT’) or enclosed in double-quotes, in which case the text is read as is, without interpretation of escape sequences.
If word is prefixed with - (a dash), then all leading
tab characters are stripped from input lines and the line containing
word. Furthermore, if - is followed by a single space,
all leading whitespace is stripped from them. This allows to indent
here-documents in a natural fashion. For example:
<<- TEXT
All leading whitespace will be
ignored when reading these lines.
TEXT
It is important that the terminating delimiter be the only token on its line. The only exception to this rule is allowed if a here-document appears as the last element of a statement. In this case a semicolon can be placed on the same line with its terminating delimiter, as in:
help-text <<-EOT
A sample help text.
EOT;
However, terminated semicolon after a here-document is optional.
shared-namespace ("/home", "/var/spool/common");
In any case where a list is appropriate, a single value is allowed without being a member of a list: it is equivalent to a list with a single member. This means that, e.g. ‘shared-namespace /home;’ is equivalent to ‘shared-namespace (/home);’.
A block statement introduces a logical group of another statements. It consists of a keyword, followed by an optional value, and a sequence of statements enclosed in curly braces, as shown in example below:
tcp-wrappers {
enable yes;
allow-syslog-priority info;
deny-syslog-priority notice;
}
The closing curly brace may be followed by a semicolon, although this is not required.
An include statement is a special statement that causes inclusion of a named file. This statement has the following syntax:
include file;
If file names a regular file, the contents of this file is included in this point. Otherwise, if file names a directory, Mailutils searches in that directory for a file whose name coincides with the name of utility being executed, and includes this file, if it exists.
It is a common approach to end the site-wide configuration file with an include statement, e.g.:
include /etc/mailutils.d;
This allows each particular utility to have its own configuration file. Thus. imap4d will read /etc/mailutils.d/imap4d, etc.
logging {
# Set syslog facility.
facility name;
# Tag syslog messages with this string.
tag text;
}
The logging block statement provides configuration for
programs that use syslog for diagnostics. The default
syslog facility is determined at compile time, it can be inspected
using the following command:
$ mailutils-config --info log_facility
Use syslog facility name. Valid argument values are: ‘user’, ‘daemon’, ‘auth’, ‘authpriv’, ‘mail’, ‘cron’, ‘local0’ through ‘local7’ (all names case-insensitive), or a facility number.
Tag syslog messages with text. By default, program name is used as syslog tag.
debug {
# Set Mailutils debugging level.
level spec;
# Prefix debug messages with Mailutils source locations.
line-info bool;
}
The debug statement configures debugging output. Although it
is mostly useful for Mailutils developers, it may be of interest for
casual users as well. In particular, you may use it to obtain more
information about Mailutils actions, which may help in configuring it,
or in filling a bug report.
Debugging output is controlled by a set of levels, each of which can be enabled or disabled independently of others. A debugging level consists of a module name, which defines a Mailutils module affected by this level, and a level number, which defines the verbosity of the debugging output. Valid debugging levels are:
Table 2.2: Debugging levels
The most important debugging modules are:
Due to its specific nature, this debugging module cannot be enabled
using level statement below. The --debug-level
command line option should be used instead
(). Alternatively, you may use the following
hook, provided to facilitate debugging of the configuration parser: a
pragmatic comment in form:
#debug=level
is understood as a request to set debugging level of module
‘config’ to level.
This statement enables debugging levels given by spec. The argument is an list of debugging specifications or a string with specifications delimited by semicolons. The syntax of a specification is:
module[[:]=level]where module is the name of a module, and level is the level to be set. The level may be optionally prefixed with the following symbols:
- ‘!’
- All levels except this one. E.g. ‘config=!trace7’ means set all debugging levels, except ‘trace7’ for the ‘config’ module.
- ‘<’
- All levels up to and including this. The words ‘up to’ refer to the position of levels in Table 2.2 table, so that, e.g. ‘<trace2’ means levels ‘error’, ‘trace0’, ‘trace1’ and ‘trace2’.
Both prefixes can be used together, in this order: ‘!<’. This means all levels except this one and ones listed before it in the table.
A comma before equal sign, as in ‘mailbox:=<trace7’ means set this debugging levels in all modules, invoked by this one.
The level in the level specification can also be a comma-separated list of valid levels, e.g.:
mailbox=<trace2,!<trace4which means “levels trace3 and trace4”.
The following example illustrates two equivalent ways of setting debugging level in a configuration file:
level ("mailbox=!proto", "acl=<trace7"); level "mailbox=!proto;acl=<trace7";The --debug-level command line option overrides the settings of the
levelconfiguration statement.
If bool is ‘true’ (see boolean value), each debugging message will be preceded by a corresponding source file location, i.e. the file name and line number where this message was generated.
mailbox {
# Use specified url as a mailspool.
mail-spool url;
# Create mailbox url using pattern.
mailbox-pattern pattern;
# Default mailbox type.
mailbox-type type;
# Default user mail folder.
folder dir;
}
The mailbox statement configures the location, name and type of
user mailboxes.
The mailbox location can be specified using mail-spool or
mail-pattern statements.
The
mail-spoolstatement specifies directory that holds user mailboxes. Once this statement is given, the libmailutils library will assume that the mailbox of user login is kept in file path/login.Historically, path can contain mailbox type prefix, e.g.: ‘maildir:///var/spool/mail’, but such usage is discouraged in favor of
mailbox-patternstatement.
The
mailbox-patternstatement is a modern way of configuring mailbox locations. It supersedesmail-spoolstatement.The pattern is valid mailbox URL, which may contain references to ‘user’ macro-variable (). This macro-variable will be expanded to the actual user name. The full syntax for pattern is:
[type://]path[;args]where:
- type
- Specifies the mailbox type. It must be one of mailbox types, supported by Mailutils. . By default, ‘local’ is assumed. .
- path
- The path pattern.
- args
- A semicolon-separated list of optional arguments, configuring indexed directory structure.
An indexed directory structure is a special way of storing mailboxes, which allows for faster access in case of very large number of users.
By default, all user mailboxes are stored in a single directory and are named after user login names. To find the mailbox for a given user, the system scans the directory for the corresponding file. This usually implies linear search, so the time needed to locate a mailbox is directly proportional to the ordinal number of the mailbox in the directory.
GNU Mailutils supports three types of indexed directories: ‘direct’, ‘reverse’, and ‘hashed’.
In direct indexed directory structure, path contains 26 subdirectories named with lower-case letters of Latin alphabet. The location of the user mailbox is determined using the following algorithm:
- Take the first letter of the user name.
- Map it to a lower-case letter using index mapping table. The result gives sub-directory name.
- Descend into this directory.
For example, using this algorithm, the mailbox of the user ‘smith’ is stored in file path/s/smith.
If each of single-letter subdirectories contains the indexed directory structure, we have second level of indexing. In this case the file name of ‘smith’'s mailbox is path/s/m/smith.
The reverse indexed structure uses the same principles, but the indexing letters are taken from the end of the user name, instead of from the beginning. For example, in the 2nd level reverse indexed structure, the ‘smith’'s mailbox is located in path/h/t/smith.
Finally, the hashed structure consists of 256 subdirectories under path, named by 2-letter hex codes from ‘00’ to ‘FF’. Mailboxes are stored in these subdirectories. The name of the subdirectory is computed by hashing first level letters of the user name. The hashing algorithm is:
- Take next letter from the user name
- Add its ASCII value to the hash sum.
- Continue (1-2) until level letters are processed, or all letters from the file name are used, whichever occurs first.
- Convert the computed sum modulo 256 to a hex code.
Indexed directory structures are configured using the following arguments:
- type=value
- Specifies type of indexing. Valid values are ‘index’, for direct indexed structure, ‘rev-index’ for reverse indexing, and ‘hash’ for hashed structure.
- param=number
- Specifies indexing level.
- user=string
- Specifies indexing key. The only meaningful value, as of Mailutils version 2.0 is ‘user=${user}’.
Let's assume the traditional mail layout, in which user incoming mails are stored in UNIX mailbox format in /var/mail directory. The
mailbox-patternfor this case is:mailbox-pattern "/var/mail/${user}";It is entirely equivalent to specifying ‘mail-spool "/var/mail"’.
Now, if the layout is the same, but mailboxes are kept in ‘maildir’ format, then the corresponding statement is:
mailbox-pattern "maildir:///var/mail/${user}";Finally, if the mailboxes are stored in a directly-indexed directory with two levels of indexing, than:
mailbox-pattern "maildir:///var/mail;type=index;param=2;user=${user}";
If neither mailbox-pattern nor mail-spool are given, the
mailbox names are determined using the following algorithm:
The built-in mail spool directory name is determined at compile time, using ‘_PATH_MAILDIR’ define from the include file paths.h. If this value is not defined, /var/mail or /usr/spool/mail is used.
Specifies type of mailboxes. By default, ‘mbox’ (UNIX mailbox) is assumed. This can be changed while configuring the package by setting
MU_DEFAULT_SCHEMEconfiguration variable. The default value can be verified by running mailutils-config --info scheme.
Sets user mail folder directory. Its value is using when expanding ‘plus-notation’, i.e. such mailbox names as +inbox. The ‘+’ sign is replaced by dir, followed by a directory separator (‘/’).
The dir argument can contain mailbox type prefix, e.g ‘mh://Mail’.
The default folder name is ‘Mail/’.
locking {
# Default locker flags.
flags arg;
# Set timeout for acquiring the lock.
retry-timeout arg;
# Set the maximum number of times to retry acquiring the lock.
retry-count number;
# Expire locks older than this amount of time.
expire-timeout number;
# Use prog as external locker program.
external-locker prog;
}
This block statement configures various parameters used when locking UNIX mailboxes in order to prevent simultaneous writes.
It is important to note, that locking applies only to maildrops in UNIX mailbox format. All other mailbox types do not require locking.
Set locking flags. Argument is a string consisting of one or more of the following letters:
- E
- Use an external program to manage locks. The program is given by
external-lockerstatement (see below).- R
- If the locking attempt failed, retry it. This is the default. The number of retries, and time interval between the two successive attempts is given by
retry-countandretry-timeoutstatements, correspondingly.- T
- If a lock file exists, check its modification time and, if it is older than a predefined amount of time, remove the lock. The amount of time is specified by
expire-timeoutstatement.- P
- Store the PID of the locking process in a lock file.
Number of locking attempts. The ‘P’ flag must be set for this to take effect.
Time interval, in seconds, between the two successive locking attempts. The ‘P’ flag must be set for this to take effect.
Remove existing lock file, if it is created more than this number of seconds ago. The ‘T’ flag must be set for this to take effect.
Set command line of an external locker program. The ‘E’ flag must be set for this to take effect.
mailer {
url url;
}
A mailer is a special logical entity GNU Mailutils uses for
sending messages. Its internal representation is discussed in
Mailer. The mailer statement configures it.
The mailer statement contains a single sub-statement:
GNU Mailutils supports two types of mailer URLs, described in the table below. As usual, square brackets indicate optional parts:
_PATH_SENDMAIL macro in your
/usr/include/paths.h. It is the default mailer.
The progname must be a full pathname of the binary file. When sending message, Mailutils will invoke this file with the arguments specified by query and will pipe the message to be sent to its standard input.
The query part is a list of arguments, separated by ‘&’ signs. Arguments may contain the following macro-substitutions:
acl {
# Allow connections from this IP address.
allow [from] ip;
# Deny connections from this IP address.
deny [from] ip;
# Log connections from this IP address.
log [from] ip [string];
/* Execute supplied program if a connection from this
IP address is requested. */
exec [from] ip program;
/* Use program to decide whether to allow connection
from ip. */
ifexec [from] ip program;
}
The ACL statement defines an Access Control List, a special structure that controls who can access the given Mailutils resource.
The acl block contains a list of access controls. Each control
can be regarded as a function that returns a tree-state value:
‘True’, ‘False’ and ‘Don't know’. When a
remote party connects to the server, each of controls is tried in
turn. If a control returns ‘False’, access is denied. If it
returns ‘True’, access is allowed. If it returns ‘Don't
know’, then the next control is tried. It is unclear whether to allow
access if the last control in list returned ‘Don't know’. GNU
Mailutils 2.0 issues a warning message and allows access.
This default may change in future versions. Users are advised to
write their ACLs so that the last control returns a definitive answer
(either True or False).
In the discussion below, wherever ip appears as an argument, it can be replaced by any of:
The following controls are understood:
When a connection from the cidr block is requested, execute the program program. If its exit code is ‘0’, then allow connection. Otherwise, deny it.
The following two controls are provided for logging purposes and as a means of extensions. They always return a ‘Don't know’ answer, and therefore should not be used at the end of an ACL:
Log connections from addresses in this cidr. The
MU_DIAG_INFOchannel is used. If the logging goes to syslog, it is translated to theLOG_INFOpriority.If string is not given, the format of the log entry depends on the connection family, as described in the table below:
- {AF_INET ip:port}
- For inet IPv4 connections. The variables ip and port are replaced by the remote IP address and port number, correspondingly.
- {AF_UNIX}
- For connections over UNIX sockets. The socket name, if available, may be printed before the closing curly brace.
If the string is specified, it undergoes macro expansion and the result of it is used as the log entry. The following macro variables are expanded:
aclno- Ordinal number of the control in the ACL. Numbers begin from ‘0’.
family- Connection family. Mailutils version 2.0 supports two families: ‘AF_INET’ and ‘AF_UNIX’.
address- Remote IP address (for ‘AF_INET’) or socket name (for ‘AF_UNIX’). Notice that most Unixes return empty string instead of the ‘AF_UNIX’ socket name, so do not rely on it.
port- Remote port number (for ‘AF_INET’).
For example, the following ACL makes a Mailutils server log every incoming connection:
acl { log from any "Connect from ${address}"; ... }This was the default behavior for the versions of Mailutils up to ‘1.2’, so if you got used to its logs you might wish to add the above in your configuration files.
If a connection from the cidr block is requested, execute the given program. Do not wait for it to terminate, and ignore its exit code.
tcp-wrappers {
# Enable TCP wrapper access control.
enable bool;
# Set daemon name for TCP wrapper lookups.
daemon name;
# Use file for positive client address access control.
allow-table file;
# Use file for negative client address access control.
deny-table file;
# Log allowed accesses at this syslog priority.
allow-syslog-priority prio;
# Log denied accesses at this syslog priority.
deny-syslog-priority prio;
}
The tcp-wrappers statements provides an alternative way to
control accesses to the resources served by GNU Mailutils. This
statement is enabled if Mailutils is compiled with TCP wrappers
library libwrap.
Access control using TCP wrappers is based on two files, called tables, containing access rules. There are two tables: the allow table, usually stored in file /etc/hosts.allow, and the deny table, kept in file /etc/hosts.deny. The rules in each table begin with an identifier called daemon name. Each utility wishing to verify a connection, select the entries having its daemon name from the allow table. A connection is allowed if it matches any of these entries. Otherwise, the utility retrieves all entries with its daemon name from the deny table. If any of these matches the connection, then it is refused. Otherwise, if neither table contains matching entries, the connection is allowed.
Description of a TCP wrapper table format lies outside the scope of this document. Please, see ACCESS CONTROL FILES, for details.
Set daemon name for TCP wrapper lookups. By default, the name of the utility is used. E.g. imap4d uses ‘imap4d’ as the daemon name.
GNU Mailutils offers several server applications: pop3d, imap4d, comsatd, to name a few. Being quite different in their purpose, they are very similar in some aspects of their architecture. First of all, they all support two operating mode: a daemon mode, where a program disconnects from the controlling terminal and works in background, and an inetd mode, where it remains in foreground and communicates with the remote party via standard input and output streams. Secondly, when operating as daemons, they listen to a preconfigured set of IP addresses and ports, reacting to requests that arrive.
To configure these aspects of functionality, GNU Mailutils provides Server Configuration Settings, which we will describe in this subsection.
# Set daemon mode. mode ‘inetd|daemon’; # Run in foreground. foreground bool; # Maximum number of children processes to run simultaneously. max-children number; # Store PID of the master process in file. pidfile file; # Default port number. port portspec; # Set idle timeout. timeout time;
These statements configure general server-related issues.
Set operation mode of the server. Two operation modes are supported:
- daemon
- Run as a standalone daemon, disconnecting from the controlling terminal and continuing to run in the background. In this case, it is the server that controls what IP addresses and ports to listen on, who is allowed to connect and from where, how many clients are allowed to connect simultaneously, etc. Most remaining configuration statements are valid only in the daemon mode.
This is the preferred mode of operation for GNU Mailutils servers.
- inetd
- Operate as a subprocess of UNIX internet super-server program, inetd. See Internet super-server, for a detailed description of the operation of inetd and its configuration. In this case it is inetd that controls all major connectivity aspects, the Mailutils server itself communicates with it via standard input and output streams.
For historical reasons, this mode is the default, if no
modestatement is specified. This will change in the future.
[daemon mode only]
Do not disconnect from the controlling terminal and remain in the foreground.
[daemon mode only]
Set maximum number of child processes allowed to run simultaneously. This equals the number of clients that can use the server simultaneously.The default is 20 clients.
After startup, store the PID of the main server process in file. When the process terminates, the file is removed. As of version 2.0, GNU Mailutils servers make no further use of this file. It is intended for use by automated startup scripts and controlling programs ().
[daemon mode only]
Set default port to listen to. The portspec argument is either a port number in decimal, or a symbolic service name, as listed in /etc/services (see Internet network services list).
Set maximum idle time out in seconds. If a client does not send any requests during time seconds, the child process terminates.
server ipaddr[:port] {
# Run this server as a single process.
single-process bool;
# Log the session transcript.
transcript bool;
# Set idle timeout.
timeout time;
# Set server specific ACLs.
acl { /* See ACL Statement. */ };
}
The server block statement configures a single TCP or UDP
server. It takes effect only in daemon mode (see server mode).
The argument to this statement specifies the IP address, and,
optionally, the port, to listen on for requests. The ipaddr
part is either an IPv4 address in dotted-quad form, or a symbolic host
name which can be resolved to such an address via DNS. Specifying
‘0.0.0.0’ as the ipaddr means listen on all available
network interfaces. The port argument is either a port number
in decimal, or a symbolic service name, as listed in
/etc/services (see Internet network services list). If port is omitted,
Mailutils uses the port set by port statement (see port), or, in its absence, the default port
number, which depends on a server being used (e.g. 110, for
pop3d, 143, for imap4d, etc.).
Any number of server statements may be specified in a single
configuration file, allowing to set up the same service on several IP
addresses and/or port numbers, and with different configurations.
Statements within the server block statement configure this
particular server.
If set to true, this server will operate in single-process mode. This mode is intended for debugging only, do not use it on production servers.
Enable transcript of the client-server interaction. This may generate excessive amounts of logging, which in turn may slow down the operation considerably.
Session transcripts are useful in fine-tuning your configurations and in debugging. They should be turned off on most production servers.
Set idle timeout for this server. This overrides global timeout settings (see timeout).
This statement defines a per-server Access Control List. Its syntax is as described in ACL Statement. Per-server ACLs complement, but not override, global ACLs, i.e. if both global ACL and per-server ACL are used, the connection is allowed only if both of them allow it, and is denied if any one of them denies it.
auth {
# Set a list of modules for authentication.
authentication module-list;
# Set a list of modules for authorization.
authorization module-list;
}
Some mail utilities provide access to their services only after verifying that the user is actually the person he is claiming to be. Such programs are, for example, pop3d and imap4d. The process of the verification is broken down into two stages: authorization and authentication. In authorization stage the program retrieves the information about a particular user. In authentication stage, this information is compared against the user-supplied credentials. Only if both stages succeed is the user allowed to use the service.
A set of modules is involved in performing each stage. For example, the authorization stage can retrieve the user description from various sources: system database, SQL database, virtual domain table, etc. Each module is responsible for retrieving the description from a particular source of information. The modules are arranged in a module list. The modules from the list are invoked in turn, until one of them succeeds or the list is exhausted. In the latter case the authorization fails. Otherwise, the data returned by the succeeded module are used in authentication.
Similarly, authentication may be performed in several ways. The authentication modules are also grouped in a list. Each module is tried in turn until either a module succeeds, in which case the authentication succeeds, or the end of the list is reached.
For example, the authorization list
(system, sql, virtdomains)
means that first the system user database (/etc/password) is searched for a description of a user in question. If the search fails, the SQL database is searched. Finally, if it also fails, the search is performed in the virtual domain database.
Note, that some authentication and/or authorization modules may be disabled when configuring the package before compilation. The names of the disabled modules are nevertheless available for use in runtime configuration options, but they represent a “fail-only” functionality, e.g. if the package was compiled without SQL support then the module ‘sql’ in the above example will always fail, thus passing the execution on to the next module.
The auth statement configures authentication and authorization.
Define a sequence of modules to use for authorization. Modules will be tried in the same order as listed in module-list.
The modules available for use in authorization list are:
- system
- User credentials are retrieved from the system user database (/etc/password).
- sql
- User credentials are retrieved from a SQL database. A separate configuration statement,
sql, is used to configure it (see SQL Statement).- virtdomain
- User credentials are retrieved from a “virtual domain” user database. Virtual domains are configured using
virtdomainstatement (see Virtdomain Statement).- radius
- User credentials are retrieved using RADIUS. See Radius Statement, for a detailed description on how to configure it.
- ldap
- User credentials are retrieved from an LDAP database. See LDAP Statement, for an information on how to configure it.
Unless overridden by
authorizationstatement, the default list of authorization modules is:(system, sql, virtdomains)
Define a sequence of modules to use for authentication. Modules will be tried in the same order as listed in module-list.
The following table lists modules available for use in module-list:
- generic
- The generic authentication type. User password is hashed and compared against the hash value returned in authorization stage.
- system
- The hashed value of the user password is retrieved from /etc/shadow file on systems that support it.
- sql
- The hashed value of the user password is retrieved from a SQL database using query supplied by
getpassstatement (see getpass).- pam
- The user is authenticated via pluggable authentication module (PAM). The PAM service name to be used is configured in
pamstatement (see PAM Statement).- radius
- The user is authenticated on a remote RADIUS server. See Radius Statement.
- ldap
- The user is authenticated using LDAP. See LDAP Statement.
Unless overridden by
authenticationstatement, the list of authentication modules is:(generic, system, pam, sql)
pam {
# Set PAM service name.
service text;
}
The pam statement configures PAM authentication. It
contains a single sub-statement:
Define service name to look for in PAM configuration. By default, the base name of the Mailutils binary is used.
This statement takes effect only if ‘pam’ is listed in
authentication statement (see Auth Statement).
virtdomain {
# Name of the virtdomain password directory.
passwd-dir dir;
}
Virtual mail domains make it possible to handle several mail domains each having a separate set of users, on a single server. The domains are completely independent of each other, i.e. the same user name can be present in several domains and represent different users.
When authenticating to a server with virtual domain support enabled,
users must supply their user names with domain parts. The server strips
off the domain part and uses it as a name of UNIX-format password
database file, located in the domain password directory. The
latter is set using passwd-dir statement.
For example, when authenticating user ‘smith@domain.tld’, the server will use password file named dir/domain.tld. This file must be in UNIX passwd format (see password file), with encrypted passwords stored in it (as of GNU Mailutils version 2.0, there is no support for shadow files in virtual password directories, although this is planned for future versions). Here is an example record from this file:
smith:Wbld/G2Q2Le2w:1000:1000:Email Account:/var/mail/domain/smith:/dev/null
Notice, that it must contain user names without domain parts.
The pw_dir field (the 6th field) is used to determine the
location of the maildrop for this user. It is defined as
pw_dir/INBOX. In our example, the maildrop for user
‘smith’ will be located in file /var/mail/domain/smith.
If user did not supply his domain name, or if no matching record was found in the password file, or if the file matching the domain name does not exist, then GNU Mailutils falls back to alternative method. First, it tries to determine the IP address of the remote party. Then the domain name corresponding to that address is looked up in the DNS system. Finally, this domain name is used as a name of the password file.
radius {
# Set radius configuration directory.
directory dir;
# Radius request for authorization.
auth request;
# Radius request for getpwnam.
getpwnam request;
# Radius request for getpwuid.
getpwuid request;
}
The radius block statement configures RADIUS
authentication and