configuration (GNU Mailutils Manual)

3.2 Mailutils Configuration File

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:

Main site-wide configuration file.
It is named sysconfdir/mailutils.conf, where sysconfdir stands for the system configuration directory set when compiling the package. You can obtain the value of sysconfdir by running
```
$ mailutils 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 any of --no-site-config or --no-config command line options was given.

Older versions of GNU Mailutils read configuration from file mailutils.rc. To facilitate transition, mailutils will look for that file as well. If both the default site-wide configuration file and legacy configuration file are present you will get the following warning:
```
legacy configuration file /etc/mailutils.rc ignored
```
Otherwise, if mailutils.conf does not exist and mailutils.rc is present, it will be used instead and the following warning will be issued:
```
 using legacy configuration file /etc/mailutils.rc:
 please rename it to /etc/mailutils.conf
```
Per-user configuration file.
Client utilities, such as frm or sieve, look in the user home directory for a file named ‘.prog’, where prog is the name of the utility. If present, this file will be loaded after loading the site-wide configuration file. For example, the per-user configuration file for sieve utility is named .sieve.

Loading of per-user configuration file is disabled by --no-user-config and --no-config options.

Server programs, such as imap4d don’t use per-user configuration files.

The --no-config option provides a shortcut for disabling loading of the default configuration files. For servers, its effect is the same as of --no-site-config. For client utilities, it is equivalent to --no-site-config --no-user-config used together.

The --config-file command line option instructs the program to read configuration from the file supplied as its argument. In that case, default configuration files are not used at all.

Neither site-wide nor user configuration files are required to exist. If any or both of them are absent, GNU Mailutils won’t complain – the utility will silently fall 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: parsing file `/etc/mailutils.conf'
imap4d: finished parsing file `/etc/mailutils.conf'

Specifying this option more than once adds more verbosity to this output. If this option is given two times, GNU Mailutils will print each 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: parsing file `/etc/mailutils.conf'
# 1 "/etc/mailutils.conf"
mailbox {
# 2 "/etc/mailutils.conf"
  mailbox-pattern maildir:/var/spool/mail;type=index;param=2;user=${user};
# 3 "/etc/mailutils.conf"
  mailbox-type maildir;
};
# 6 "/etc/mailutils.conf"
include /etc/mailutils.d;
imap4d: parsing file `/etc/mailutils.d/imap4d'
...

To test configuration file without actually running 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.conf

and to edit the imap4d.conf file with your editor of choice.

The order in which configuration files are loaded defines the precedence of their settings. Thus, for client utilities, settings from the per-user configuration file override those from the site-wide configuration.

It is also possible to set or override arbitrary configuration variables in the command line. It can be done via the --set option. Its argument is a pathname of the variable to be set, followed by an equals sign and a value. For example, to define the variable ‘syslog’ in section ‘logging’ to ‘no’, do the following:

$ imap4d --set .logging.syslog=no

Configuration pathnames are discussed in detail in Paths. For a detailed description of this option, the --set option.

The --set options are processed after loading all configuration files.

3.2.1 Configuration File Syntax

The configuration file consists of statements and comments.

There are three classes of lexical tokens: keywords, values, and separators. 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.

3.2.1.1 Comments

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 may well appear within multi-line ones.

3.2.1.2 Statements

A simple statement consists of a keyword and value separated by any amount of whitespace. Simple statement is terminated with a semicolon (‘;’).

The following is a simple statement:

standalone yes;
pidfile /var/run/pop3d.pid;

A keyword begins with a letter and may contain letters, decimal digits, underscores (‘_’) and dashes (‘-’). Examples of keywords are: ‘expression’, ‘output-file’.

A value can be one of the following:

number

A number is a sequence of decimal digits.

boolean

A boolean value is one of the following: ‘yes’, ‘true’, ‘t’ or ‘1’, meaning true, and ‘no’, ‘false’, ‘nil’, ‘0’ meaning false.

unquoted string

An unquoted string may contain letters, digits, and any of the following characters: ‘_’, ‘-’, ‘.’, ‘/’, ‘@’, ‘*’, ‘:’.

quoted string

A quoted string is any sequence of characters enclosed in double-quotes (‘"’). A backslash appearing within a quoted string introduces an escape sequence, which is replaced with a single character according to the following rules:

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)
\v	Vertical tabulation character (ASCII 11)
\\	A single backslash (‘`\`’)
\"	A double-quote.

Table 3.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"

Here-document

A here-document is a special construct that allows to introduce strings of text containing embedded newlines.

The <<word construct instructs the parser to read all the following lines 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

The body of a here-document is interpreted the same way as a 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
    The 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;

list

A list is a comma-separated list of values. Lists are enclosed in parentheses. The following example shows a statement whose value is a list of strings:

alias (test,null);

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.

alias test;

is equivalent to

alias (test);

A block statement introduces a logical group of statements. It consists of a keyword, followed by an optional value, and a sequence of statements enclosed in curly braces, as shown in the example below:

server srv1 {
  host 10.0.0.1;
  community "foo";
}

The closing curly brace may be followed by a semicolon, although this is not required.

3.2.1.3 Statement Path

Mailutils configuration files have a distinct hierarchical structure. Each statement in such files can therefore be identified by its name and the names of block statements containing it. Such names form the pathname, similar to that used by UNIX file system.

For example, consider the following file:

foo {
  bar {
    baz 45;   # A.
  }
  baz 98;     # B.
}

The full pathname of the statement marked with ‘A’ can be written as:

.foo.bar.baz

Similarly, the statement marked with ‘B’ has the following pathname:

.foo.baz

The default path component separator is dot. A pathname beginning with a component separator is called absolute pathname. Absolute pathnames uniquely identify corresponding statements. If the leading dot is omitted, the resulting pathname is called relative. Relative pathnames identify statements in relation to the current point of reference in the configuration file.

Any other punctuation character can be used as a component separator, provided that it appears at the beginning of the pathname. In other words, only absolute pathnames allow for a change in component separators.

A block statement that has a tag is referred to by the statement’s name, followed by an equals sign, followed by the tag value. For example, the statement ‘A’ in the file below:

program x {
  bar {
    baz 45;   # A.
  }
}

is identified by the following pathname:

.program=x.bar.baz

The tag can optionally be enclosed in a pair of double quotes. Such a quoting becomes mandatory for tags that contain white space or path component separator, e.g.:

.program="a.out".bar.baz

The --set command line option allows you to set configuration variables from the command line. Its argument consists of the statement path and value, separated by a single equals sign (no whitespace is permitted at either side of it). For example, the following option:

--set .logging.facility=mail

has the same effect as the following statement in the configuration file:

logging {
    facility mail;
}

Values set using this option override those set in the configuration files. This provides a convenient way for temporarily changing configuration without altering configuration files.

Notice, that when using --set, the ‘=’ sign has two purposes: first it separates statement path from the value, thus forming an assignment, and secondly it can be used within the path itself to introduce a tag. To illustrate this, let’s assume you have the following statement in your configuration file:

program pop3d {
    logging {
       facility mail;
    }
    server 0.0.0.0 {
       transcript no;
    }
}

Now assume you wish to temporarily change logging facility to ‘local1’. The following option will do this:

--set .program=pop3d.logging.facility=local1

When splitting the argument to --set, the option parser always looks for the rightmost equals sign. Everything to the right of it is the value, and everything to the left of it - the path.

If the tag contains dots (as the server statement in the example above), you should either escape them with slashes or change the pathname separator to some other character, e.g.:

--set .program=pop3d.server='0\.0\.0\.0'.transcript=yes

--set /program=pop3d/server="0.0.0.0"/transcript=yes

3.2.2 Configuration Variables

Certain configuration statements allow for the use of variable references in their values. A variable reference has the form ‘$variable’ or ‘${variable}’, where variable is the variable name. It is expanded to the actual value of variable when Mailutils consults the configuration statement in question.

The two forms are entirely equivalent. The form with curly braces is normally used if the variable name is immediately followed by an alphanumeric symbol, which will otherwise be considered part of it. This form also allows for specifying the action to take if the variable is undefined or expands to an empty value.

During variable expansion, the forms below cause Mailutils to test for a variable that is unset or null. Omitting the colon results in a test only for a variable that is unset.

${variable:-word}: Use Default Values. If variable is unset or null, the expansion of word is substituted. Otherwise, the value of variable is substituted.
${variable:=word}: Assign Default Values. If variable is unset or null, the expansion of word is assigned to variable. The value of variable is then substituted.
${variable:?word}: Display Error if Null or Unset. If variable is null or unset, the expansion of word (or a message to that effect if word is not present) is output to the current logging channel. Otherwise, the value of variable is substituted.
${variable:+word}: Use Alternate Value. If variable is null or unset, nothing is substituted, otherwise the expansion of word is substituted.

When a value is subject to variable expansion, it is also subject to command expansion. Commands are invoked in string values using the following format:

$(cmd arg)

where cmd is the command name, and args is a list of arguments separated by whitespace. Arguments can in turn contain variable and command references.

The following commands are defined:

Command: localpart string: Treats string as an email address and returns the part preceding the ‘@’ sign. If there is no ‘@’ sign, returns string.

Command: domainpart string: Treats string as an email address and returns the part following the ‘@’ sign. If there is no ‘@’ sign, returns empty string.

Command: shell cmd args: Runs the shell command cmd with the given arguments. Returns the standard output from the command. The command is invoked using /bin/sh -c and can contain any valid shell constructs.

The subsections below define variable names that are valid for use in each configuration statement.

3.2.3 The `include` Statement

A special statement is provided that causes inclusion of the named file. It has the following syntax:

include file;

When reading the configuration file, this statement is effectively replaced with the content of file. It is an error if file does not exist.

In site-wide configuration file, file can be a directory name. In this case, Mailutils will search this directory for a file with the same name as the utility being executed. If found, this file will be loaded.

It is a common 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.

3.2.4 The `program` statement

Another way to configure program-specific settings is by using the program statement. The syntax is as follows:

program progname {
   ...
}

The program statement is allowed only in the site-wide configuration file. When encountered, its tag (progname) is compared with the name of the program being run. If two strings are the same, the statements between curly braces are stored in a temporary memory, otherwise the statement is ignored. When entire configuration file is loaded, the statements accumulated in the temporary storage are processed.

Notice the difference between this statement and a per-program configuration file loaded via an include statement. No matter where in the file the program statement is, its content will be processed after the content of the enclosing file. In the contrast, the per-program configuration file loaded via include is processed right where it is encountered.

3.2.5 The `logging` Statement

Syntax

logging {
  # Send diagnostics to syslog.
  syslog boolean;
  
  # Print message severity levels.
  print-severity boolean;
  
  # Output only messages with a severity equal to or
  # greater than this one.
  severity string;
  
  # Set syslog facility.
  facility name;

  # Log session ID
  session-id boolean;
    
  # Tag syslog messages with this string.
  tag text;
}

Description

The logging block statement configures where the diagnostic output goes and how verbose it is.

Configuration: syslog bool: If ‘syslog’ is set to ‘yes’, the diagnostics will go to syslog. Otherwise, it goes to the standard error.

The default syslog facility is determined at compile time, it can be inspected using the following command (see mailutils info):

$ mailutils info log_facility

Configuration: facility name: 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.

Configuration: tag text: Tag syslog messages with text. By default, program name is used as syslog tag.

Configuration: print-severity bool: Print Mailutils severity name before each message.

Configuration: severity name: Output only messages with a severity equal to or greater than this one. Valid arguments are: ‘debug’, ‘info’, ‘notice’, ‘warning’, ‘error’, ‘crit’, ‘alert’, ‘emerg’,

Configuration: session-id bool: Print session ID with each diagnostic message. This is useful for programs that handle multiple user sessions simultaneously, such as pop3d and imap4d.

3.2.6 The `debug` Statement

Syntax

debug {
  # Set Mailutils debugging level.
  level spec;
  
  # Prefix debug messages with Mailutils source locations.
  line-info bool;
}

Description

The ‘debug’ statement controls the amount of additional debugging information output by Mailutils programs. The ‘level’ statement enables additional debugging information. Its argument (spec) is a Mailutils debugging specification as described in debugging.

The ‘line-info’ statement, when set to ‘true’ causes debugging messages to be prefixed with locations in Mailutils source files where they appear. Normally, only Mailutils developers need this option.

3.2.7 The `mailbox` Statement

Syntax

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;
}

Description

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.

Configuration: mail-spool path

The mail-spool statement 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-pattern statement.

Configuration: mailbox-pattern url

The mailbox-pattern statement is a preferred way of configuring mailbox locations. It supersedes mail-spool statement.

The url must be a valid mailbox URL (see Mailbox), which may contain references to the ‘user’ variable (see Variables). This variable will be expanded to the actual user name.

Optional URL parameters can be used to configure indexed directory structure. Such 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 the name of a sub-directory where the mailbox is located.
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 the 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 3.14 is ‘user=${user}’.

Let’s assume the traditional mail layout, in which incoming mails are stored in a UNIX mailbox named after the recipient user name and located in /var/mail directory. The mailbox-pattern for 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, the URL is:

  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:

If environment variable FOLDER is set, use its value.
Otherwise, if environment variable MAIL is set, use its value.
If neither of these is set, construct the mailbox name by concatenating the built-in mail spool directory name, a directory separator, and the user name.
The built-in mail spool directory name is determined at compile time, using the ‘_PATH_MAILDIR’ define from the include file paths.h. If this value is not defined, /var/mail or /usr/spool/mail is used.

Configuration: mailbox-type type: Specifies the type of mailboxes. By default, ‘mbox’ (UNIX mailbox) is assumed. This can be changed while configuring the package by setting MU_DEFAULT_SCHEME configuration variable. The default value can be verified by running mailutils info scheme.

Configuration: folder dir

Sets user mail folder directory. Its value is used 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/’.

3.2.8 The `mime` Statement

Syntax

mime {
  # Define additional textual mime types.
  text-type PATTERN;
  # or
  text-type ( PATTERN-LIST );
}

Description

The mime compound statement is used by utilities that process MIME messages, in particular mail, readmsg, and decodemail. As of mailutils version 3.14 it contains only one statement:

Configuration: text-type pattern

Configuration: text-type ( pattern-list )

Defines additional patterns for recognition of textual message parts. The pattern is a shell globbing pattern that will be compared against the ‘Content-Type’ header of a MIME message part in order to determine whether it can be treated as a text part. In second form, pattern-list is a comma-separated list of such patterns.

In both forms, the new patterns are appended to the built-in textual pattern list, which contains:

text/*
application/*shell
application/shellscript
*/x-csrc
*/x-csource
*/x-diff
*/x-patch
*/x-perl
*/x-php
*/x-python
*/x-sh

3.2.9 The `locking` Statement

Syntax

locking {
  # Default locker flags.
  type default | dotlock | external | kernel | null;
  
  # Set the maximum number of times to retry acquiring the lock.
  retry-count number;
  
  # Set the delay between two successive locking attempts.
  retry-sleep arg;
  
  # Expire locks older than this amount of time.
  expire-timeout number;

  # Check if PID of the lock owner is active, steal the lock if it not. 
  pid-check bool;

  # Use prog as external locker program.
  external-locker prog;
}

Description

This compound 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 monolithic mailboxes, i.e. mailboxes of ‘mbox’ and ‘dotmail’ types (see mbox). Other mailbox types don’t require locking.

Configuration: type string

Set locking type. Allowed arguments are:

default

Default locking type. As of mailutils version 3.14, this is equivalent to dotlock.

dotlock

A ‘dotlock’-style locking. To lock a mailbox named X a lock file named X.lock is created. If pid-check yes is set, this file will contain the PID of the locking process, so that another process wishing to acquire the lock could verify if the lock is still in use.

external

Run external program to perform locking/unlocking operations. The name of the program is given by the external-locker statement (see below). If it is not given, the built-in default ‘dotlock’ is used.

The locker program is invoked as follows:

# To lock mbox:
locker -fexpire_timeout -rretry_count mbox
# To unlock it:
locker -u -fexpire_timeout -rretry_count mbox

Here, expire_timeout is the value supplied with the expire-timeout configuration statement, and retry_count is the value supplied with the retry-count statement (see below).

To properly interact with mailutils, the external locker program must use the following exit codes:

Exit code	Meaning
0	Success.
1	Failed due to an error.
2	Unlock requested (`-u`), but file is not locked.
3	Lock requested, but file is already locked.
4	Insufficient permissions.

See dotlock, for the description of the default external locker, shipped with mailutils.

kernel

Use kernel locking mechanism (fcntl(2)).

null

No locking at all. The statements below are silently ignored.

Configuration: retry-count number: Number of locking attempts. The default is 10.

Configuration: retry-sleep seconds
Configuration: retry-timeout seconds: Time interval, in seconds, between two successive locking attempts. The default is 1 second. The retry-timeout statement is deprecated because of its misleading name.

Configuration: expire-timeout seconds: Sets the expiration timeout. The existing lock file will be removed, if it was created more than this number of seconds ago. The default is 600.

Configuration: pid-check bool: This statement can be used if locking type is set to dotlock. If set to true, it instructs the locking algorithm to check if the PID of the lock owner is still running by the time when it tries to acquire the lock. This works as follows. When the lock file is created, the PID of the creating process is written to it. If another process tries to acquire the lock and sees that the lock file already exists, it reads the PID from the file and checks if a process with that PID still exists in the process table. If it does not, the process considers the lock file to be stale, removes it and locks the mailbox.

Configuration: external-locker string

Sets the name of the external locker program to use, instead of the default ‘dotlock’.

This statement is in effect only when used together with type external.

3.2.10 The `mailer` Statement

Syntax

mailer {
  url url;
}

Description

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:

Configuration: url str: Set the mailer URL.

GNU Mailutils supports three types of mailer URLs, described in the table below:

smtp://[user[:pass][;auth=mech,...]@]host[:port][;params]

smtps://[user[:pass][;auth=mech,...]@]host[:port][;params]

Send messages using SMTP protocol. See SMTP Mailboxes, for a detailed description of the URL and its parts.

sendmail[://progname]

Use sendmail-compatible program progname. Sendmail-compatible means that the program must support following command line options:

-oi: Do not treat ‘.’ as message terminator.
-f addr: Use addr as the sender address.
-t: Get recipient addresses from the message.

See sendmail, for details.

prog://progname?query

A prog mailer. This is a generalization of ‘sendmail’ mailer that allows to use arbitrary external programs as mailers.

It is described in detain in prog.

3.2.11 The `acl` Statement

Syntax

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;
}

Description

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 3.14 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 definite answer (either True or False).

In the discussion below, wherever cidr appears as an argument, it can be replaced by any of:

An IPv4 address in dotted-quad notation.
An IPv6 address in numeric notation
A CIDR in the form ‘ip/mask’, where ip is an IP address (either IPv4 or IPv6), and mask is the network mask.
A symbolic host name.
A word ‘any’, which matches any IP address.

The following controls are understood:

Configuration: allow [from] cidr: Allow connections from IP addresses matching this cidr block.

Configuration: deny [from] cidr: Deny connections from IP addresses matching this cidr block.

Configuration: ifexec [from] cidr program

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 program argument undergoes variable expansion and word splitting. The following variables are defined:

aclno: Ordinal number of the control in the ACL. Numbers begin from ‘1’.
family: Connection family. Mailutils version 3.14 supports the following families: ‘AF_INET’, ‘AF_INET6’ and ‘AF_UNIX’.
address: Remote IP address (for ‘AF_INET’ and ‘AF_INET6’) 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’ and ‘AF_INET6’).

Configuration: exec [from] cidr program: 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. The program is subject for variable expansion as in ‘ifexec’.

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:

Configuration: log [from] cidr [string]

Log connections from addresses in this cidr. The MU_DIAG_INFO channel is used. If the logging goes to syslog, it is translated to the LOG_INFO priority.

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 string is supplied, it undergoes variable expansions as described for the ‘ifexec’.

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.

Configuration: exec [from] cidr program: 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.

3.2.12 The `tcp-wrappers` Statement

Syntax

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;
}

Description

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. A utility that wishes to verify a connection, selects 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.

The description of a TCP wrapper table format lies outside the scope of this document. Please, see ACCESS CONTROL FILES in hosts_access(5) man page, for details.

Configuration: enable bool: Enable access control using TCP wrappers. It is on by default.

Configuration: daemon name: 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.

Configuration: allow-table file: Use file as allow table. By default, /etc/hosts.allow is used.

Configuration: deny-table file: Use file as negative table. By default, /etc/hosts.deny is used.

3.2.13 Server Settings

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 modes: daemon, where a program disconnects from the controlling terminal and works in background, and inetd, 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 is describes in this subsection.

3.2.13.1 General Server Configuration

Syntax:

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

Description: These statements configure general server-related issues.

Configuration: mode string;

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 in inetd(8) man page, 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 program communicates with it via standard input and output streams.

For historical reasons, this mode is the default, if no mode statement is specified. This will change in the future.

Configuration: foreground bool;: [daemon mode only]
Do not disconnect from the controlling terminal and remain in the foreground.

Configuration: max-children number;

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

Configuration: pidfile file;: After startup, store the PID of the main server process in file. When the process terminates, the file is removed. As of version 3.14, GNU Mailutils servers make no further use of this file. It is intended for use by automated startup scripts and controlling programs (e.g. see GNU pies in GNU Pies Manual).

Configuration: port portspec;: [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 in services(5) man page).

Configuration: timeout time;: Sets maximum idle time out in seconds. If a client does not send any requests during time seconds, the child process terminates.

3.2.13.2 The `server` Statement

Syntax:

server ipaddr[:port] {
  # Run this server as a single process.
  single-process bool;
  
  # Log the session transcript.
  transcript bool;

  # Set idle timeout.
  timeout time;

  # Size of the queue of pending connections
  backlog <number: callback>;

  # Kind of TLS encryption to use for this server.
  tls-mode ‘no’|‘ondemand’|‘required’|‘connection’;

  tls {
    # Specify SSL certificate file.
    ssl-certificate-file string;
    # Specify SSL certificate key file.
    ssl-key-file file;
    # Specify trusted CAs file.
    ssl-ca-file file;
    # Set the priorities to use on the ciphers, methods, etc.
    ssl-priorities string;
    # Set timeout for I/O operations during TLS handshake (seconds).
    handshake-timeout n;
  }
  
  # Set server specific ACLs.
  acl { /* See ACL Statement. */ };
}

Description:

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 IPv6 address enclosed in square brackets, or a symbolic host name which can be resolved to such an address. 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 in services(5) man page). 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.

Configuration: single-process bool;: 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.

Configuration: transcript bool;

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.

Configuration: timeout time;: Set idle timeout for this server. This overrides the global timeout settings (see timeout).

Configuration: backlog number;: Configures the size of the queue of pending connections

Configuration: tls-mode mode;

Configure the use of TLS encryption. The mode argument is one of the following:

no: TLS is not used. The corresponding command (STLS, for POP3, STARTTLS, for IMAP4) won’t be available even if the TLS configuration is otherwise complete.
ondemand: TLS is initiated when the user issues the appropriate command. This is the default when TLS is configured.
required: Same as above, but the use of TLS is mandatory. The authentication state is entered only after TLS negotiation has succeeded.
connection: TLS is always forced when the connection is established. For pop3d this means using POP3S protocol (or IMAP4S, for imap4d).

Configuration: tls { ... }

The tls statement configures SSL certificate and key files, as well as other SSL settings for use in this server. It is used when tls-mode is set to any of the following values: ondemand, required, connection.

If tls-mode is set to any of the values above and tls section is absent, settings from the global tls section will be used. In this case, it is an error if the global tls section is not defined.

See tls statement, for a discussion of its syntax.

Configuration: acl: 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.

3.2.14 The `auth` Statement

Syntax

auth {
  # Set a list of modules for authentication.
  authentication module-list;
  
  # Set a list of modules for authorization.
  authorization module-list;
}

Description

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.

Configuration: authorization module-list

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 virtdomain statement (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 authorization statement, the default list of authorization modules is:

generic
system
pam
sql
virtual
radius
ldap

Configuration: authentication module-list

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 getpass statement (see getpass).
pam: The user is authenticated via pluggable authentication module (PAM). The PAM service name to be used is configured in pam statement (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 authentication statement, the list of authentication modules is the same as for authorization, i.e.:

generic
system
pam
sql
virtual
radius
ldap

3.2.15 PAM Statement

Syntax

pam {
  # Set PAM service name.
  service text;
}

Description

The pam statement configures PAM authentication. It contains a single sub-statement:

Configuration: service text: 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).

3.2.16 The `virtdomain` Statement

Syntax

virtdomain {
  # Name of the virtdomain password directory.
  passwd-dir dir;
}

Description

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.

Configuration: passwd-dir dir: Set virtual domain password directory.

For example, when authenticating user ‘smith@example.com’, the server will use password file named dir/example.com. This file must be in UNIX passwd format (see password file in passwd(5) man page), with encrypted passwords stored in it (as of GNU Mailutils version 3.14, 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.

3.2.17 The `radius` Statement

Syntax

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;
}

Description

The radius block statement configures RADIUS authentication and authorization.

Mailutils uses GNU Radius library, which is configured via raddb/client.conf file (see Client Configuration in GNU Radius Reference Manual). Its exact location depends on configuration settings that were used while compiling GNU Radius. Usually it is /usr/local/etc, or /etc. This default can also be changed at run time using directory statement:

Configuration: directory dir: Set full path name to the GNU Radius configuration directory.

It authorization is used, the Radius dictionary file must declare the the following attributes:

Attribute	Type	Description
GNU-MU-User-Name	string	User login name
GNU-MU-UID	integer	UID
GNU-MU-GID	integer	GID
GNU-MU-GECOS	string	GECOS
GNU-MU-Dir	string	Home directory
GNU-MU-Shell	string	User shell
GNU-MU-Mailbox	string	User mailbox
GNU-MU-Quota	integer	Mail quota (in bytes)

A dictionary file with appropriate definitions is included in the Mailutils distribution: examples/config/mailutils.dict. This file is not installed by default, you will have to manually copy it to the GNU Radius raddb/dict directory and include it in the main dictionary file raddb/dictionary by adding the following statement:

$INCLUDE dict/mailutils.dict

Requests to use for authentication and authorization are configured using three statements: auth, getpwnam and getpwuid. Each statement takes a single argument: a string, containing a comma-separated list of assignments. An assignment specifies a particular attribute-value pair (see RADIUS Attributes in GNU Radius Reference Manual) to send to the server. The left-hand side of the assignment is a symbolic attribute name, as defined in one of Radius dictionaries (see Dictionary of Attributes in GNU Radius Reference Manual). The value is specified by the right-hand side of assignment. For example:

"Service-Type = Authenticate-Only, NAS-Identifier = \"mail\""

The assignment may contain references to the following variables (see Variables):

user

The actual user name (for auth and getpwnam), or user ID (for getpwuid). For example:

User-Name = ${user}

passwd

User password. For examples:

User-Password = ${passwd}

Configuration: auth pairlist

Specifies the request to be sent to authenticate the user. For example:

auth "User-Name = ${user}, User-Password = ${passwd}";

The user is authenticated only if this request returns Access-Accept (see Access-Accept in GNU Radius Reference Manual). Any returned attribute-value pairs are ignored.

Configuration: getpwnam pairlist

Specifies the request that returns user information for the given user name. For example:

getpwnam "User-Name = ${user}, State = getpwnam, "
         "Service-Type = Authenticate-Only";

If the requested user account exists, the Radius server must return Access-Accept packet with the following attributes: GNU-MU-User-Name, GNU-MU-UID, GNU-MU-GID, GNU-MU-GECOS, GNU-MU-Dir, GNU-MU-Shell.

The attributes GNU-MU-Mailbox and GNU-MU-Quota are optional.

If GNU-MU-Mailbox is present, it must contain a valid mailbox URL (see URL). If GNU-MU-Mailbox is not present, Mailutils constructs the mailbox name using the settings from the mailbox configuration statement (see Mailbox Statement), or built-in defaults, if it is not present.

If GNU-MU-Quota is present, it specifies the maximum mailbox size for this user, in bytes. In the absence of this attribute, mailbox size is unlimited.

Configuration: getpwuid pairlist

Specifies the request that returns user information for the given user ID. In pairlist, the ‘user’ macro-variable is expanded to the numeric value of ID. For example:

getpwuid "User-Name = ${user}, State = getpwuid, "
         "Service-Type = Authenticate-Only";

The reply to getpwuid request is the same as to getpwnam request (see above).

3.2.18 The `sql` Statement

Syntax

sql {
  # Set SQL interface to use.
  interface ‘mysql|odbc|postgres’;
  # SQL server host name.
  host arg;
  # SQL user name.
  user arg;
  # Password for the SQL user.
  passwd arg;
  # SQL server port.
  port arg;
  # Database name.
  db arg;
  # Type of password returned by getpass query.
  password-type ‘plain | hash | scrambled’;
  # Set a field-map for parsing SQL replies.
  field-map list;
  # SQL query returning the user’s password.
  getpass query;
  # SQL query to use for getpwnam requests.
  getpwnam query;
  # SQL query to use for getpwuid requests.
  getpwuid query;
}

Description

The sql statement configures access credentials to SQL database and the queries for authentication and authorization.

GNU Mailutils supports three types of SQL interfaces: MySQL, PostgreSQL and ODBC. The latter is a standard API for using database management systems, which can be used to communicate with a wide variety of DBMS.

Configuration: interface type

Configures type of DBMS interface. Allowed values for type are:

mysql: Interface with a MySQL server (http://www.mysql.org).
odbc: Use ODBC interface. See http://www.unixodbc.org, for a detailed description of ODBC configuration.
postgres: Interface with a PostgreSQL server (http://www.postgres.org).

The database and database access credentials are configured using the following statements:

Configuration: host arg: The host running the SQL server. The value can be either a host name or an IP address in dotted-quad notation, in which case an INET connection is used, or a full pathname to a file, in which case a connection to UNIX socket is used.

Configuration: port arg: TCP port the server is listening on (for INET connections). This parameter is optional. Its default value depends on the type of database being used.

Configuration: db arg;: Name of the database.

Configuration: user arg: SQL user name.

Configuration: passwd arg;: Password to access the database.

Configuration: password-encryption arg;

Defines type of encryption used by the password returned by getpass query (see below). Possible arguments are:

plain: Password is in plain text.
crypt
hash: Password is encrypted by system crypt function (see crypt in crypt(3) man page).
scrambled: Password is encrypted by MySQL password function.

Configuration: getpwnam query

Defines SQL query that returns information about the given user. The query is subject to variable expansion (see Variables). The only variable defined is ‘$user’, which expands to the user name.

The query should return a single row with the following columns:

name: User name.
passwd: User password.
uid: UID of the user.
gid: GID of the primary group.
gecos: Textual description of the user.
dir: User’s home directory
shell: User’s shell program.

The following columns are optional:

mailbox: Full pathname of the user’s mailbox. If not returned or NULL, the mailbox is determined using the default algorithm (see Mailbox).
quota: Upper limit on the size of the mailbox. The value is either an integer number optionally followed by one of the usual size suffixes: ‘K’, ‘M’, ‘G’, or ‘T’ (case-insensitive).

Configuration: getpwuid query

Defines SQL query that returns information about the given UID. The query is subject to variable expansion (see Variables). The only variable defined is ‘$user’, which expands to the UID.

The query should return a single row, as described for getpwnam.

Configuration: getpass query

Defines SQL query that returns the password of the given user. The query is subject to variable expansion (see Variables). The only variable defined is ‘$user’, which expands to the user name.

The query should return a row with a single column, which gives the password. The password can be encrypted as specified by the password-encryption statement.

Configuration: field-map list

Defines a translation map for column names. The list is a list of mappings. Each mapping is a string ‘name=column’, where name is one of the names described in getpw column names, and column is the name of the column in the returned row that should be used instead. The effect of this statement is similar to that of SQL AS keyword. E.g. the statement

field-map (uid=user_id);

has the same effect as using ‘SELECT user_id AS uid’ in the SQL statement.

3.2.19 The `ldap` Statement

Syntax

ldap {
  # Enable LDAP lookups.
  enable bool;
  # Set URL of the LDAP server.
  url url;
  # Base DN for LDAP lookups.
  base string;
  # DN for accessing LDAP database.
  binddn string;
  # Password for use with binddn.
  passwd string;
  # Use TLS encryption.
  tls bool;
  # Set LDAP debugging level.
  debug number;
  # Set a field-map for parsing LDAP replies.
  field-map list;
  # LDAP filter to use for getpwnam requests.
  getpwnam string;
  # LDAP filter to use for getpwuid requests.
  getpwuid filter;
}

Description

The ldap statement configures the use of LDAP for authentication.

Configuration: enable bool: Enables LDAP lookups. If absent, ‘enable On’ is assumed.

Configuration: url url: Sets the URL of the LDAP server.

Configuration: base string: Defines base DN for LDAP lookups.

Configuration: binddn string: Defines the DN for accessing LDAP database.

Configuration: passwd string: Password for use when binding to the database.

Configuration: tls bool: Enable the use of TLS when connecting to the server.

Configuration: debug number: Set LDAP debug level. Please refer to the OpenLDAP documentation, for allowed number values and their meaning.

Configuration: field-map map

Defines a map for parsing LDAP replies. The map is a list of mappings¹. Each mapping is ‘field=attr’, where attr is the name of the LDAP attribute and field is a field name that declares what information that attribute carries. Available values for field are:

name: User name.
passwd: User password.
uid: UID of the user.
gid: GID of the primary group.
gecos: Textual description of the user.
dir: User’s home directory
shell: User’s shell program.

The default mapping is

  ("name=uid",
   "passwd=userPassword",
   "uid=uidNumber",
   "gid=gidNumber",
   "gecos=gecos",
   "dir=homeDirectory",
   "shell=loginShell")

Configuration: getpwnam string

Defines the LDAP filter to use for ‘getpwnam’ requests. The default is:

  (&(objectClass=posixAccount) (uid=$user))

Configuration: getpwuid string

Defines the LDAP filter to use for ‘getpwuid’ requests. The default filter is:

  (&(objectClass=posixAccount) (uidNumber=$user))

3.2.20 The `tls` Statement

Syntax

tls {
  # Specify SSL certificate file.
  ssl-certificate-file string;
  # Specify SSL certificate key file.
  ssl-key-file file;
  # Specify trusted CAs file.
  ssl-ca-file file;
  # Set the priorities to use on the ciphers, methods, etc.
  ssl-priorities string;
  # Set timeout for I/O operations during TLS handshake (seconds).
  handshake-timeout n;
}

Description

The ‘tls’ statement configures TLS parameters to be used by servers. It can appear both in the global scope and in server scope. Global tls settings are applied for servers that are declared as supporting TLS encryption, but lack the ‘tls’ substatement.

Configuration: ssl-certificate-file string: Specify SSL certificate file.

Configuration: ssl-key-file file: Specify SSL certificate key file.

Configuration: ssl-ca-file file: Specify the trusted certificate authorities file.

Configuration: ssl-priorities string: Set the priorities to use on the ciphers, key exchange methods, MACs and compression methods.

Configuration: handshake-timeout n: Set the timeout (in seconds) for I/O operations during TLS handshake. Default value is 10 seconds.

3.2.21 The `tls-file-checks` Statement

Syntax

tls-file-checks {
  # Configure safety checks for SSL key file.
  key-file list;
  # Configure safety checks for SSL certificate.
  cert-file list;
  # Configure safety checks for SSL CA file.
  ca-file list;
}

Description

This section configures security checks applied to the particular SSL configuration files in order to decide whether it is safe to use them.

Configuration: key-file list

Configure safety checks for SSL key file. Elements of the list are names of individual checks, optionally prefixed with ‘+’ to enable or ‘-’ to disable the corresponding check. Valid check names are:

none: Disable all checks.
all: Enable all checks.
gwrfil: Forbid group writable files.
awrfil: Forbid world writable files.
grdfil: Forbid group readable files.
ardfil: Forbid world writable files.
linkwrdir: Forbid symbolic links in group or world writable directories.
gwrdir: Forbid files in group writable directories.
awrdir: Forbid files in world writable directories,

Configuration: cert-file list: Configure safety checks for SSL certificate. See key-file for a description of list.

Configuration: ca-file list: Configure safety checks for SSL CA file. See key-file for a description of list.

3.2.22 The `gsasl` Statement

Editor’s note:

This node is to be written.

Syntax

gsasl {
  # Name of GSASL password file.
  cram-passwd file;
  # SASL service name.
  service string;
  # SASL realm name.
  realm string;
  # SASL host name.
  hostname string;
  # Anonymous user name.
  anonymous-user string;
}

Footnotes

(1)

For backward compatibility, map can be a string containing colon-delimited list of mappings. Such usage is, however, deprecated.

This document was generated on January 2, 2022 using makeinfo.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

GNU Mailutils

General-Purpose Mail Package

3.2 Mailutils Configuration File

3.2.1 Configuration File Syntax

3.2.1.1 Comments

3.2.1.2 Statements

3.2.1.3 Statement Path

3.2.2 Configuration Variables

3.2.3 The include Statement

3.2.4 The program statement

3.2.5 The logging Statement

Syntax

Description

3.2.6 The debug Statement

Syntax

Description

3.2.7 The mailbox Statement

Syntax

Description

3.2.8 The mime Statement

Syntax

Description

3.2.9 The locking Statement

Syntax

Description

3.2.10 The mailer Statement

Syntax

Description

3.2.11 The acl Statement

Syntax

Description

3.2.12 The tcp-wrappers Statement

Syntax

Description

3.2.13 Server Settings

3.2.13.1 General Server Configuration

3.2.13.2 The server Statement

3.2.14 The auth Statement

Syntax

Description

3.2.15 PAM Statement

Syntax

Description

3.2.16 The virtdomain Statement

Syntax

Description

3.2.17 The radius Statement

Syntax

Description

3.2.18 The sql Statement

Syntax

Description

3.2.19 The ldap Statement

Syntax

Description

3.2.20 The tls Statement

Syntax

Description

3.2.21 The tls-file-checks Statement

Syntax

Description

3.2.22 The gsasl Statement

Syntax

Footnotes

(1)

3.2.3 The `include` Statement

3.2.4 The `program` statement

3.2.5 The `logging` Statement

3.2.6 The `debug` Statement

3.2.7 The `mailbox` Statement

3.2.8 The `mime` Statement

3.2.9 The `locking` Statement

3.2.10 The `mailer` Statement

3.2.11 The `acl` Statement

3.2.12 The `tcp-wrappers` Statement

3.2.13.2 The `server` Statement

3.2.14 The `auth` Statement

3.2.16 The `virtdomain` Statement

3.2.17 The `radius` Statement

3.2.18 The `sql` Statement

3.2.19 The `ldap` Statement

3.2.20 The `tls` Statement

3.2.21 The `tls-file-checks` Statement

3.2.22 The `gsasl` Statement