![[MU Poststamp]](/graphics/mustamp.png)
|
|
GNU Mailutils |
General-Purpose Mail Package |
Official GNU Software |
GNU Mailutils Manual (split by chapter): 
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.
Display a short summary of the command line options understood by this utilities, along with a terse description of each.
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.
Display a short summary of options. In the contrast to the --help option, only option names and arguments are printed, without any textual description. For example:
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.
Print program version and exit.
Show configuration options used when compiling the package. You can use this option to verify if support for a particular mailbox format or other functionality is compiled in the binary. The output of this option is intended to be both machine-readable and understandable by humans.
The following command line options affect parsing of configuration files. Here we provide a short summary, the next section will describe them in detail.
Load this configuration file, instead of the default.
Show configuration file summary.
Check configuration file syntax and exit
Verbosely log parsing of the configuration files.
Do not load site-wide configuration file.
Do not load user configuration file.
Don’t load site-wide and user configuration files.
Set configuration variable. See the --set option.
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.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
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.
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.
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.
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:
A number is a sequence of decimal digits.
A boolean value is one of the following: ‘yes’, ‘true’, ‘t’ or ‘1’, meaning true, and ‘no’, ‘false’, ‘nil’, ‘0’ meaning false.
An unquoted string may contain letters, digits, and any of the following characters: ‘_’, ‘-’, ‘.’, ‘/’, ‘@’, ‘*’, ‘:’.
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"
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;
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.
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
or
--set /program=pop3d/server="0.0.0.0"/transcript=yes
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.
Use Default Values. If variable is unset or null, the expansion of word is substituted. Otherwise, the value of variable is substituted.
Assign Default Values. If variable is unset or null, the expansion of word is assigned to variable. The value of variable is then substituted.
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.
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:
Treats string as an email address and returns the part preceding the ‘@’ sign. If there is no ‘@’ sign, returns string.
Treats string as an email address and returns the part following the ‘@’ sign. If there is no ‘@’ sign, returns empty string.
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.
include StatementA 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.
program statementAnother 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.
logging Statementlogging {
# 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;
}
The logging block statement configures where the diagnostic
output goes and how verbose it is.
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
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.
Print Mailutils severity name before each message.
Output only messages with a severity equal to or greater than this one. Valid arguments are: ‘debug’, ‘info’, ‘notice’, ‘warning’, ‘error’, ‘crit’, ‘alert’, ‘emerg’,
Print session ID with each diagnostic message. This is useful for
programs that handle multiple user sessions simultaneously, such as
pop3d and imap4d.
debug Statementdebug {
# Set Mailutils debugging level.
level spec;
# Prefix debug messages with Mailutils source locations.
line-info bool;
}
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.
mailbox Statementmailbox {
# 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-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.
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:
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:
Indexed directory structures are configured using the following arguments:
Specifies the type of indexing. Valid values are ‘index’, for direct indexed structure, ‘rev-index’ for reverse indexing, and ‘hash’ for hashed structure.
Specifies indexing level.
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:
FOLDER is set, use its value.
MAIL is set, use its
value.
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.
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.
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/’.
mime Statementmime {
# Define additional textual mime types.
text-type PATTERN;
# or
text-type ( PATTERN-LIST );
}
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:
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:
locking Statementlocking {
# 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;
}
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.
Set locking type. Allowed arguments are:
defaultDefault locking type. As of mailutils version
3.14, this is equivalent to dotlock.
dotlockA ‘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.
externalRun 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.
kernelUse kernel locking mechanism (fcntl(2)).
nullNo locking at all. The statements below are silently ignored.
Number of locking attempts. The default is 10.
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.
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.
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.
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.
mailer Statementmailer {
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:
Set the mailer URL.
GNU Mailutils supports three types of mailer URLs, described in the table below:
Send messages using SMTP protocol. See SMTP Mailboxes, for a detailed description of the URL and its parts.
Use sendmail-compatible program progname. Sendmail-compatible means that the program must support following command line options:
Do not treat ‘.’ as message terminator.
Use addr as the sender address.
Get recipient addresses from the message.
See sendmail, for details.
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.
acl Statementacl {
# 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 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:
The following controls are understood:
Allow connections from IP addresses matching this cidr block.
Deny connections from IP addresses matching this cidr block.
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:
aclnoOrdinal number of the control in the ACL. Numbers begin from ‘1’.
familyConnection family. Mailutils version 3.14 supports the following families: ‘AF_INET’, ‘AF_INET6’ and ‘AF_UNIX’.
addressRemote 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.
portRemote port number (for ‘AF_INET’ and ‘AF_INET6’).
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:
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:
For inet IPv4 connections. The variables ip and port are replaced by the remote IP address and port number, correspondingly.
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.
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 Statementtcp-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;
}
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.
Enable access control using TCP wrappers. It is on by default.
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.
Use file as allow table. By default, /etc/hosts.allow is used.
Use file as negative table. By default, /etc/hosts.deny is used.
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.
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.
Set operation mode of the server. Two operation modes are supported:
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.
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.
[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 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).
[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).
Sets maximum idle time out in seconds. If a client does not send any requests during time seconds, the child process terminates.
server StatementSyntax:
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.
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 the global timeout settings (see timeout).
Configures the size of the queue of pending connections
Configure the use of TLS encryption. The mode argument is one of the following:
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.
TLS is initiated when the user issues the appropriate command. This is the default when TLS is configured.
Same as above, but the use of TLS is mandatory. The authentication state is entered only after TLS negotiation has succeeded.
TLS is always forced when the connection is established. For
pop3d this means using POP3S protocol (or IMAP4S, for
imap4d).
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.
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 Statementauth {
# 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:
User credentials are retrieved from the system user database (/etc/password).
User credentials are retrieved from a SQL database.
A separate configuration statement, sql, is used to configure
it (see sql statement).
User credentials are retrieved from a “virtual domain” user
database. Virtual domains are configured using virtdomain
statement (see virtdomain statement).
User credentials are retrieved using RADIUS. See radius statement, for a detailed description on how to configure it.
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:
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:
The generic authentication type. User password is hashed and compared against the hash value returned in authorization stage.
The hashed value of the user password is retrieved from /etc/shadow file on systems that support it.
The hashed value of the user password is retrieved from a
SQL database using query supplied by getpass
statement (see getpass).
The user is authenticated via pluggable authentication module
(PAM). The PAM service name to be used is
configured in pam statement (see pam statement).
The user is authenticated on a remote RADIUS server. See radius statement.
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.:
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 Statementvirtdomain {
# 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.
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.
radius Statementradius {
# 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 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:
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):
The actual user name (for auth and getpwnam), or user ID
(for getpwuid). For example:
User-Name = ${user}
User password. For examples:
User-Password = ${passwd}
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.
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.
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).
sql Statementsql {
# 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;
}
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.
Configures type of DBMS interface. Allowed values for type are:
Interface with a MySQL server (http://www.mysql.org).
Use ODBC interface. See http://www.unixodbc.org, for a detailed description of ODBC configuration.
Interface with a PostgreSQL server (http://www.postgres.org).
The database and database access credentials are configured using the following statements:
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.
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.
Name of the database.
SQL user name.
Password to access the database.
Defines type of encryption used by the password returned by
getpass query (see below). Possible arguments are:
Password is in plain text.
Password is encrypted by system crypt function
(see crypt in crypt(3) man page).
Password is encrypted by MySQL password function.
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:
User name.
User password.
UID of the user.
GID of the primary group.
Textual description of the user.
User’s home directory
User’s shell program.
The following columns are optional:
Full pathname of the user’s mailbox. If not returned or NULL, the mailbox is determined using the default algorithm (see Mailbox).
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).
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.
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.
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.
ldap Statementldap {
# 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;
}
The ldap statement configures the use of LDAP for authentication.
Enables LDAP lookups. If absent, ‘enable On’ is assumed.
Sets the URL of the LDAP server.
Defines base DN for LDAP lookups.
Defines the DN for accessing LDAP database.
Password for use when binding to the database.
Enable the use of TLS when connecting to the server.
Set LDAP debug level. Please refer to the OpenLDAP documentation, for allowed number values and their meaning.
Defines a map for parsing LDAP replies. The map is a list of mappings1. 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:
User name.
User password.
UID of the user.
GID of the primary group.
Textual description of the user.
User’s home directory
User’s shell program.
The default mapping is
("name=uid",
"passwd=userPassword",
"uid=uidNumber",
"gid=gidNumber",
"gecos=gecos",
"dir=homeDirectory",
"shell=loginShell")
Defines the LDAP filter to use for ‘getpwnam’ requests. The default is:
(&(objectClass=posixAccount) (uid=$user))
Defines the LDAP filter to use for ‘getpwuid’ requests. The default filter is:
(&(objectClass=posixAccount) (uidNumber=$user))
tls Statementtls {
# 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;
}
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.
Specify SSL certificate file.
Specify SSL certificate key file.
Specify the trusted certificate authorities file.
Set the priorities to use on the ciphers, key exchange methods, MACs and compression methods.
Set the timeout (in seconds) for I/O operations during TLS handshake. Default value is 10 seconds.
tls-file-checks Statementtls-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;
}
This section configures security checks applied to the particular SSL configuration files in order to decide whether it is safe to use them.
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:
Disable all checks.
Enable all checks.
Forbid group writable files.
Forbid world writable files.
Forbid group readable files.
Forbid world writable files.
Forbid symbolic links in group or world writable directories.
Forbid files in group writable directories.
Forbid files in world writable directories,
Configure safety checks for SSL certificate. See
key-file for a description of list.
Configure safety checks for SSL CA file. See
key-file for a description of list.
gsasl Statement|
Editor’s note:
This node is to be written. |
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;
}
Mailutils debugging output is controlled by a set of levels, each of
which can be set independently of others. Each debug level consists of
a category name, which identifies the part of
Mailutils for which additional debugging is desired, and a
level number, which tells Mailutils how verbose should its
output be.
Valid debug levels are:
Displays error conditions which are normally not reported, but passed to the caller layers for handling.
Ten levels of verbosity, ‘trace0’ producing less output, ‘trace9’ producing the maximum amount of output.
Displays network protocol interaction, where applicable.
Implementation and applicability of each level differs between various categories. The full list of categories is available in file libmailutils/diag/debcat in the Mailutils source tree. Most useful categories and levels implemented for them are discussed later in this article.
Debug levels can be set either from the command line, by using the --debug-level command line option, or from the configuration file, using the ‘.debug.level’ statement. In both cases, the level is specified as a list of individual levels, delimited with semicolons. Each individual level can be specified as:
Disables all levels for the specified category.
Enables all levels for the specified category.
For the given category, enables all levels from ‘error’ to level, inclusive.
Enables only the given level for this category.
Disables all levels from ‘error’ to level, inclusive, for this category.
Disables only the given level in this category.
Enables all levels in the range from levelA to levelB, inclusive.
Disables all levels in the range from levelA to levelB, inclusive.
Additionally, a comma-separated list of level specifications is allowed after the dot. For example, the following specification:
acl.prot,!=trace9,!trace2
enables in category ‘acl’ all levels, except ‘trace9’, ‘trace0’, ‘trace1’, and ‘trace2’.
The following specification in Backus-Naur form describes formally the Mailutils debug level:
<debug-spec> ::= <level-spec> | <debug-level-list>
<debug-level-list> ::= <debug-level> |
<debug-level-list> ";" <debug-level>
<debug-level> ::= <category> | "!" <category> |
<category> "." <level-list>
<level-list> ::= <level-spec> | <level-list> "," <level-spec>
<level-spec> ::= <level> | <negate-level>
<negate-level> ::= "!" <level>
<level> ::= <level-number> | "=" <level-number> |
<level-number> "-" <level-number>
<level-number> ::= "error" | "trace0" | "trace1" | "trace2" | "trace3" |
"trace4" | "trace5" | "trace6" | "trace7" |
"trace8" | "trace9" | "prot"
This category enables debugging of Access Control Lists. Available levels are:
As usual, displays errors, not directly reported otherwise.
Basic tracing of ACL processing.
Traces the process of matching the ACL conditions.
This category affects configuration parser and/or lexical analyzer. The following levels are supported:
Minimal information about configuration statements.
Trace lexical structure of the configuration files.
Trace execution of the configuration parser.
Due to its specific nature, this category cannot be enabled from the configuration file. A special hook is provided to facilitate debugging the configuration parser, namely, a pragmatic comment in form:
#debug=debug-level-list
causes debug-level-list to be parsed as described above. Thus, to force debugging of the configuration parser, one would add the following line at the very beginning of the configuration file:
#debug=config.trace7
Operations over mailboxes. This module supports the following levels: ‘error’, ‘trace0’, ‘trace1’, and ‘prot’. The latter is used by remote mailbox support libraries.
Enables debugging information about authentication and authorization. This category supports the following levels: ‘error’, ‘trace0’, ‘trace1’, and ‘trace2’.
In level ‘trace0’, user data are reported along with the data source they were obtained from. The output may look like this:
pop3d: source=system, name=gray, passwd=x, uid=120, gid=100, gecos=Sergey Poznyakoff, dir=/home/gray, shell=/bin/bash, mailbox=/var/mail/gray, quota=0, change_uid=1
In the ‘trace1’ level, additional flow traces are displayed.
In the level ‘trace2’, a detailed flow trace is displayed, which looks like the following:
pop3d: Trying generic... pop3d: generic yields 38=Function not implemented pop3d: Trying system... pop3d: system yields 0=Success pop3d: Trying generic... pop3d: generic yields 4135=Authentication failed pop3d: Trying system... pop3d: system yields 0=Success
Debugs mailer operations. The following levels are supported:
Displays mild error conditions.
Traces mailer operations in general: displays what part of the message is being sent, etc.
When used together with ‘prot’, displays security-sensitive information (such as passwords, user keys, etc). in plaintext. By default, such information is replaced with asterisks to reduce the possibility of security compromise.
When used together with ‘prot’, displays the payload information as it is being sent. The payload is the actual message contents, i.e. the part of SMTP transaction that goes after the ‘DATA’ command and which ends with a terminating dot line. Setting this level can generate huge amounts of information.
For SMTP mailer: outputs transcripts of SMTP sessions.
Note: Unless in a very secure environment, it is advised to avoid using level settings such as mailer.prot or mailer (without explicit level part), because the resulting output tends to be extremely copious and reveals sender private and security-sensitive data. If you wish to trace SMTP session flow, use ‘mailer.=prot’ or at least ‘mailer.prot,!trace6’.
This category provides debugging information for Mailutils IP server objects. It supports the ‘error’ and ‘trace0’ levels.
This category controls debugging information shown for operations related to Mailutils folders.
The remote category is used by imap4d and pop3d
servers to request showing additional information in the session
transcripts. This category takes effect only when the transcript
configuration variable is set. Valid levels are:
Show security-sensitive information (user passwords, etc.)
Show payload information
frm and from — List Headers from a Mailbox|
Editor’s note:
The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised. |
GNU mailutils provides two commands for listing messages in a mailbox.
These are from and frm.
The behavior of both programs is affected by the following configuration file statements:
| Statement | Reference |
|---|---|
| debug | See debug statement. |
| tls | See tls statement. |
| mailbox | See mailbox statement. |
| locking | See locking statement. |
frmThe frm utility outputs a header information of
the selected messages in a mailbox. By default, frm reads
user’s system mailbox and outputs the contents of From and
Subject headers for each message. If a folder is specified in
the command line, the program reads that folder rather than the default
mailbox.
The following command line options alter the behavior of the program:
Enable debugging output.
Display the header named by string instead of From
Subject pair.
Include the contents of To header to the output. The output field
order is then: To From Subject.
Prefix each line with corresponding message number.
Be very quiet. Nothing is output except error messages. This is useful in shell scripts where only the return status of the program is important.
Print a message only if there are unread messages in the mailbox.
Print a summary line.
Only display headers from messages with the given status. Attr may be one of the following: ‘new’, ‘read’, ‘unread’. It is sufficient to specify only first letter of an attr. Multiple -s options are allowed.
Tidy mode. In this mode frm tries to preserve the alignment of
the output fields. It also enables the use of BIDI algorithm for
displaying subject lines that contain text in right-to-left
orientation (such as Arabic or Hebrew).
fromThe from utility displays sender and subject of each message
in a mailbox. By default, it reads the user’s system mailbox. If the
program is given a single argument, it is interpreted as a name of the
user whose mailbox is to be read. Obviously, permissions are required
to access that user’s mailbox, so such invocations may be used only
by superuser.
The option -f (--file) instructs from to read
the given mailbox.
The full list of options, supported by from follows:
Prints only a count of messages in the mailbox and exit.
Prints additional debugging output.
Prints only mail with ‘From:’ header containing the supplied string.
Examine mailbox from the given url.
mail — Send and Receive Mail|
Editor’s note:
The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised. |
Mail is an enhanced version of POSIX mailx program.
The program operates in two modes: read and send.
Mail enters send mode when at least one email address
was specified in its command line. In this mode the program waits
until user finishes composing the message, then attempts to send it to
the specified addresses and exits. See Composing Mail, for a
detailed description of this behavior.
If the command line contained no email addresses, mail switches
to reading mode. In this mode it allows the user to read and manipulate the
contents of the user system mailbox. Use the --file (-f)
option to specify another mailbox name. For more detail, see
Reading Mail.
In addition to the Mailutils configuration file, mail reads
the traditional ‘mailrc’-style configuration files. See Mail Configuration Files, for a detailed description of their format.
mailGeneral usage of mail program is:
mail [option...] [address...]
If [address...] part is present, mail switches to
mail sending mode, otherwise it operates in mail reading mode.
Mail understands the following command line options:
Attach file to the composed message. The encoding, content type, and content description are controlled by the --encoding, --content-type, and --content-name options, correspondingly.
The option --attach=- instructs mail to read the
file to be attached from the standard input. Interactive shell is
disabled in this case.
Read attachment body from the file descriptor fd. The
descriptor must be open for reading. This option is useful when
calling mail from another program.
See the options --encoding, --content-type, --content-name, and --content-filename.
Append the given header to the composed message.
This options sets the content type to be used by all subsequent --attach options.
Set the ‘filename’ parameter in the ‘Content-Disposition’ header for the next --attach-fd option.
Set the ‘name’ parameter (description) in the ‘Content-Type’ header for the next --attach or --attach-fd option.
Execute command before opening the mailbox. Any number of --exec options can be given. The commands will be executed after sourcing configuration files (see Mail Configuration Files), but before opening the mailbox.
Return true if the mailbox contains some messages. Return false otherwise.
This is useful for writing shell scripts.
Sets content transfer encoding for use by the subsequent --attach options.
Record outgoing messages in a file named after the first recipient. The name is the login-name portion of the address found first on the ‘To:’ line in the mail header.
Operate on the mailbox given by the first non-optional command line argument. If there is no such argument, read messages from the user’s mbox file. See Reading Mail, for more details about using this option.
Print header summary to stdout and exit.
Ignore interrupts when composing the message.
The --mime option instructs mail to compose MIME
messages. It is equivalent for -E 'set mime', except that it
is processed after all other options. The --no-mime disables
the MIME compose mode, and is a shortcut for -E 'set nomime',
Do not display initial header summary.
Do not read the system-wide mailrc file. See Mail Configuration Files.
Print all mail to standard output. It is equivalent to issuing following commands after starting ‘mail -N’:
print * quit
except that mail --print does not change status of the messages.
Cause interrupts to terminate program.
Sets the return email address for outgoing mail. See return-address.
Don’t create attachments that would have zero-size body. This option affects all attachments created by --attach and --attach-fd options appearing after it in the command line, as well as the body of the original message.
To cancel its effect, use the --no-skip-empty-attachments option.
Send a message with a Subject of subj. Valid only in sending mode.
Read recipients from the message header. Ignore addresses listed in the command line.
Operate on user’s mailbox. This is equivalent to:
mail -f/spool_path/user
with spool_path being the full path to your mailspool directory
(/var/spool/mail or /var/mail on most systems).
The program also understands the common mailutils options (see Common Options.
The mail utility operates on three kinds of mailboxes. The
user system mailbox is the mailbox where the incoming mail for
the user is stored. Its location is system-dependent and is
determined using the common mailutils rules (see mailbox statement). The personal mailbox (or mbox, for short) is
the default location for saving messages that have been read. By
default it is $HOME/mbox or whatever file specified by the
MBOX environment variable. Any other mailboxes are called
secondary mailboxes.
When called without arguments, mail opens the system mailbox
for the invoking user. The --file (-f) used without
arguments instructs mail to operate on the personal mailbox
instead. When this option and a single command line argument are used
together, mail treats the argument as the pathname of the
secondary mailbox to operate upon.
Notice that this argument is not an argument to the --file (-f) option itself, but rather the first non-optional argument on the command line. This means that any number of additional options are allowed between the --file option and the mailbox file name. For example, the following three invocations are equivalent:
$ mail -fin mymbox $ mail -f mymbox -in $ mail --file -in mymbox $ mail --file -i mymbox -n
Additionally, for conformance to the GNU standards, the following form is also accepted:
$ mail --file=mymbox -i -n
The --user (-u) option allows the system administrator to assume another user identity for operating on this user’s mailboxes. Obviously, it is available only to system administrators. For example:
mail --user=tom
reads mail from the system mailbox of the user ‘tom’, and
mail --user=tom --file
reads mail from the personal mailbox of this user.
Unless you have started mail with --norc command line option,
it will read the contents of the system-wide configuration file.
Then it will read the contents of user configuration file, if it exists.
For detailed description of these files, see Mail Configuration Files.
After this initial setup, mail displays the first page of header
lines (unless the -N option has been given), followed by a prompt,
indicating that it is waiting for regular commands. Upon receiving a
command, mail parses and executes it, displays the result on
the screen, prints the prompt and waits for the next command. This
process is continued until mail receives any of the commands
‘quit’, ‘exit’ or the end-of-file character (ASCII 4, or
C-D).
Each message in the mailbox has a state that affects how it is retained or deleted upon closing the mailbox when terminating the program (see the quit command) or when switching to another mailbox (see the file command). The state is reflected in the header listing and can be changed during the session. The states are:
The message is present in the system mailbox and has not been read
by the user or moved to any other state. When mail
terminates, messages in this state are retained in the system
mailbox. If the mailbox is closed, such messages are moved to the
‘unread’ state.
The message has been present in the system mailbox for more than one
invocation of mail and has not been read by the user or
moved to any other state. When mail terminates, messages in
this state are retained in the system mailbox.
The message has been read by the user, i.e. processed by one of the
following commands: copy, mbox, next,
pipe, prev, print, Print, struct,
top, type, Type, undelete, or any of the
following escapes (in message compose mode): ~f, ~m,
~F, ~M.
When mail terminates, messages in this state are handled
depending on the mailbox they are in.
If mail was operating on the user system mailbox, all
messages in state ‘read’ are preserved. The location where
they are preserved is determined by the hold variable
(see Mail Variables). If it is not set (the default), the
messages are moved to the user’s mbox. If hold is set,
the messages are held in the system mailbox instead.
The ‘read’ messages in any other mailbox will be retained in their current location.
The message has been processed by one of the following commands: ‘delete’, ‘dp’, ‘dt’. Messages in this state are ignored by any command, excepting ‘undelete’, which changes their state back to ‘read’. When closing the mailbox, deleted messages are permanently removed from the mailbox.
The message has been processed by the preserve (hold)
command. When closing the mailbox, such messages are retained in
the mailbox.
The message has been processed by one of the following commands:
save, write. When mail terminates, messages
in this state are handled depending on the mailbox they are in.
If mail was operating on the user system mailbox, the
default behavior for ‘saved’ messages is to remove them
from the system mailbox. If, however, the keepsave variable
is set, they are preserved using the same rules as for ‘read’
messages (see above).
Saved messages in non-system mailboxes are retained in their current location.
Unless the mailbox is empty, exactly one of its messages will be marked as current message. Upon startup, current message is set to the first new message, if there is any, or the first unread message if there is any, or to the first message in the mailbox. In the header listing, current message is marked with the ‘>’ sign at the beginning of the line. Current message is changed by any of the following commands: ‘dp’, ‘prev’, ‘next’.
Commands have the following syntax:
command [msglist] [argument ...]
A command is terminated by a newline character. Empty command (i.e. a newline character alone) is equivalent to ‘next’ (see next).
In the syntax above, command is the command verb. Each command has long and short (abbreviated) form. Each of them can be used to invoke the command.
Many mail commands take a list of messages (msglist) to operate upon, which defaults to current message.
The list of messages in its simplest form is one of:
| . | Selects current message. It is equivalent to empty message list. |
| * | Selects all messages in the mailbox. |
| ^ | Selects first non-deleted message. |
| $ | Selects last non-deleted message. |
In its complex form, the message list is a comma or whitespace-separated list of message specifiers. A message specifier is one of
(integer number) This specifier addresses the message with the given ordinal number in the mailbox.
All messages with ordinal numbers between n and m, inclusive.
All messages of type t, where t can be any of:
Deleted messages.
New messages.
Old messages (any message not in state ‘read’ or ‘new’).
Messages in state ‘read’.
Messages in state ‘unread’.
Selects all tagged messages.
Selects all untagged messages.
Selects all messages in state ‘saved’.
Header match.
Selects all messages that contain header field header matching
given string. If the variable regex is set, the
string is assumed to be a POSIX regexp. (All comparison is
case-insensitive in either case).
If header: part is omitted, it is assumed to be ‘Subject:’.
Message body match.
Selects all messages with body matching the string. The matching rules are the same as described above.
A message specifier can be followed by message part specifier, enclosed in a pair of brackets. A message part specifier controls which part of a message should be operated upon. It is meaningful only for multipart messages. A message part specifier is a comma or whitespace-separated list of part numbers or ranges. Each part number can in turn be message part specifier, thus allowing for operating upon multiply-encoded messages.
The following are the examples of valid message lists:
Third message.
Messages from 1 through 4 and message 10.
All messages starting from message 4.
All messages with the word ‘watch’ in the subject.
All messages with the word ‘watch’ in the subject or body.
Same as above plus the last message in the mailbox.
Part 2 of the multipart message 10.
Following commands quit the program:
Terminates the session. The messages, marked with delete are
removed. The messages in state ‘read’ and ‘saved’ are
processed depending on the mailbox they are in.
If mail was operating on the user system mailbox, all
messages in state ‘read’ are preserved. The location where
they are preserved is determined by the hold variable. If
it is not set (the default), the messages are moved to the user’s
mbox. If hold is set, the messages are held in the
system mailbox instead.
The default behavior for ‘saved’ messages is to remove them
from the system mailbox. If, however, the keepsave variable
is set, they are preserved using the same rules as for ‘read’
messages.
For non-system mailboxes, both ‘read’ and ‘saved’ messages are retained in their current location.
The same rules are followed when the mailbox is switched using the
file command.
The program exits to the shell, unless saving the mailbox fails, in which case user can escape with the exit command.
Program exits to the shell without modifying the mailbox it operates upon.
Typing EOF (‘C-D’) alone is equivalent to ‘quit’.
Following commands can be used during the session to request online help:
Display detailed command synopsis. If no command is given, help for all available commands is displayed.
Print a list of available commands.
Display program version.
Display program warranty statement.
Move to the first undeleted message.
Move to the last undeleted message.
Move to the next message.
Move to the previous message.
Change to the specified directory. If dir is omitted, $HOME is
assumed.
When used without argument, prints the information about the current mailbox: the mailbox file name (or URL), total number of messages and the number of unread messages, e.g.:
? fold "/var/spool/mail/gray": 23 messages 22 unread |
Otherwise, closes the current mailbox and opens the mailbox named by the mailbox argument. When closing the current mailbox, its messages are processed according to their state (see mail message states).
The mailbox argument can be the name of the existing file, a mailbox URL (see Mailbox), or any of the following shortcuts:
The system mailbox for the invoking user.
The system mailbox for user.
The previous file.
The user’s personal mailbox.
Secondary mailbox, given using the -f command line option.
The named file in the folder directory. See folder variable.
To control which headers in the message should be displayed, mail
keeps two lists: a retained header list and an ignored
header list. If retained header list is not empty, only the
header fields listed in it are displayed when printing the message.
Otherwise, if ignored header list is not empty, only the headers
not listed in this list are displayed. The uppercase variants
of message-displaying commands can be used to print all the headers.
The following commands modify and display the contents of both lists.
Add header-field-list to the ignored list. When used without arguments, this command prints the contents of ignored list.
Add header-field-list to the retained list. When used without arguments, this command prints the contents of retained list.
Displays the current message number.
Lists the current pageful of headers.
Lists the contents of ‘From’ headers for a given set of messages.
Presents message headers in pagefuls as described for headers
command. When arg is ‘.’, it is generally equivalent to
headers. When arg is omitted or is ‘+’, the next
pageful of headers is displayed. If arg is ‘-’, the
previous pageful of headers is displayed. The latter two forms
of z command may also take a numerical argument meaning the
number of pages to skip before displaying the headers. For
example:
? z +2
will skip two pages of messages before displaying the header summary.
Lists the message number and message size in bytes for each message in msglist.
Displays the value of folder variable.
Displays current mailbox summary. E.g.:
? summary "/var/spool/mail/gray": 23 messages 22 unread |
Prints out the messages from msglist. The variable crt
determines the minimum number of lines the body of the message must
contain in order to be piped through pager command specified
by environment variable PAGER. If crt is set to a numeric
value, this value is taken as the minimum number of lines. Otherwise,
if crt is set without a value then the height of the terminal
screen is used to compute the threshold. The number of lines on
screen is controlled by screen variable.
Like print but also prints out ignored header fields.
Print a multipart message. The decode command decodes and prints
out specified message parts. E.g.
? decode 15[2] +--------------------------------------- | Message=15[2] | Type=message/delivery-status | encoding=7bit +--------------------------------------- Content-Type: message/delivery-status ... |
Prints the top few lines of each message in msglist. The number
of lines printed is controlled by the variable toplines and
defaults to five.
Pipe the contents of specified messages through shell-command. Without arguments, pipe the current message through the command given by the ‘cmd’ variable (which must be set).
Prints the MIME structure of each message from msglist. Empty msglist means current message.
Example:
? struct 2 2 multipart/mixed 14k 2[1] text/plain 296 2[2] application/octet-stream 5k 2[3] text/x-diff 31k |
Tag messages. The tagged messages can be referred to in message list using ‘:t’ notation.
Clear tags from specified messages. To untag all messages tagged so far type
? untag :t
Marks each message to be held in user’s system mailbox. This command
does not override the effect of delete command.
Marks each message from the msglist as not having been read.
Mark messages as deleted. Upon exiting with quit command these
messages will be deleted from the mailbox. Until the end of current
session the deleted messages can be referred to in message lists using
:d notation.
Clear delete mark from the specified messages.
Deletes the current message and prints the next message. If msglist is specified, deletes all messages from the list and prints the message immediately following last deleted one.
Takes a message list and a file or mailbox name and appends each
message in turn to that file or mailbox. The syntax for mailbox
is the same as for the file command (see Mailbox shortcuts). The name of the mailbox and number of lines and
characters appended to it is echoed on the terminal. When writing to
file, the numbers represent exact number of lines and characters
appended to the file. When file specifies a mailbox, these
numbers may differ by the amount of lines/characters needed to
represent message envelope for that specific mailbox type.
Each saved message is marked for deletion as if with delete
command, unless the variable keepsave is set.
Like save, but the file to append messages to is named after the
sender of the first message in msglist. The file name is
selected as described in saving mail by name. For example:
? from 14 15 U 14 smith@noldor.org Fri Jun 30 18:11 14/358 The Save c U 15 gray@noldor.org Fri Jun 30 18:30 8/245 Re: The Sa ? Save 14 15 "smith" 22/603 |
i.e., 22 lines (603 characters) have been appended to the file “smith”. If the file does not exist, it is created.
Similar to save, except that only message body (without the
header) is saved.
Similar to Save, except that only message body (without the
header) is saved.
Mark list of messages to be saved in the user’s personal mailbox
(see personal mailbox) upon exiting via quit
command. This is the default action for all read messages, unless you
have variable hold set.
Touch the specified messages. If any message in msglist is not specifically deleted nor saved in a file, upon normal termination it will be acted upon as if it had been read (see mail message states).
Similar to save, except that saved messages are not marked as
saved.
Similar to Save, except that saved messages are not marked as
saved.
These command allow to edit messages in a mailbox. Please note,
that modified messages currently do not replace original ones. i.e.
you have to save them explicitly using your editor’s save
command if you do not want the effects of your editing to be lost.
Edits each message in msglist with the editor, specified in
EDITOR environment variable.
Edits each message in msglist with the editor, specified in
VISUAL environment variable.
With no arguments, prints out all currently-defined aliases. With one argument, prints out that alias. With more than one argument, creates a new alias or changes an old one.
Takes a list of names defined by alias commands and discards the remembered groups of users. The alias names no longer have any significance.
The alternates command is useful if you have accounts on several machines. It can be used to inform mail that the listed addresses are really you. When you reply to messages, mail will not send a copy of the message to any of the addresses listed on the alternates list. If the alternates command is given with no argument, the current set of alternate names is displayed.
Switches to compose mode. After composing the message, sends it to the specified addresses.
If the record variable is set, the composed message will be
saved in the folder named by it.
Same as mail, but the name of the file to save the composed
message is derived from its first recipient as outlined below.
If the outfolder variable is set, and has a string value s,
the filename is s/recipient. If it is a boolean,
then the folder variable is consulted. If it is set, then the
filename is folder/recipient. Otherwise, the
message will not be saved.
The value recipient is derived from the email of the first
recipient of the message. By default it is a local part of that
email. If the outfilename variable has the value
‘domain’, the domain part of the email is used. If this
variable is set to ‘email’, then entire email address is
used.
See saving mail by name, for a detailed discussion.
Mail a reply message to all recipients included in the header of the
message. The subject header is formed by concatenating the
value of the replyprefix variable and the subject from the
message. If record is set to a filename, the response is
saved at the end of that file.
Mail a reply message to the sender of each message in the msglist.
The subject header is formed by concatenating the value of the
replyprefix variable and the subject header of from the
first message in msglist. If record is set to a
filename, the response is saved at the end of that file.
Notice, that setting mail variable flipr (see Mail Variables) swaps the meanings of the two above commands
Respond to message, recording the response in a file whose name is derived from the author of the message. See saving mail by name, for a discussion of how the file name is selected.
Same as Reply, but the response is saved in a file whose name
is derived from the author of the first message. See saving mail by name, for a detailed discussion of how the file name is selected.
By default, mail will preserve personal email parts when
forming lists of recipient addresses. If this is not desired, unset
the fullnames variable (see fullnames).
To determine the sender of the message mail uses the
list of sender fields (see Controlling Sender Fields). The first field
from this list is looked up in message headers. If it is found
and contains a valid email address, this address is used as
the sender address. If not, the second field is searched and
so on. This process continues until a field is found in the
headers, or the sender field list is exhausted, whichever happens
first.
If the previous step did not determine the sender address, the address from SMTP envelope is used.
Let’s illustrate this. Suppose your mailbox contains the following:
U 1 block@helsingor.org Fri Jun 30 18:30 8/245 Re: The Sa ? Print 1 From: Antonius Block <block@helsingor.org> To: Smeden Plog <plog@helsingor.org> Date: Tue, 27 Apr 2004 13:23:41 +0300 Reply-To: <root@helsingor.org> Subject: News Hi |
Now, you issue the following commands:
? sender mail-followup-to reply-to from ? reply To: <root@helsingor.org> Subject: Re: News |
As you see, the value of Reply-To field was taken as the
sender address.
Now, let’s try the following command sequence:
# Clear the sender list ? nosender # Set new sender list ? sender From
Now, the From address will be taken:
? reply To: Antonius Block <block@helsingor.org> Subject: Re: News |
When mail needs to know the sender of a message, it
looks it up in one or more headers of that message. Such headers
constitute a sender list. The first header from the list
that is present in the message and has a non-empty value is used.
If none is found or if the sender list is empty, the value of the
message envelope is used.
The commands sender and nosender manipulate the sender
list.
If the command sender is used without arguments, it displays
the contents of the sender field list. If arguments are given,
each argument is appended to the sender field list. For example:
? sender Sender address is obtained from the envelope ? sender mail-followup-to reply-to ? sender mail-followup-to reply-to ? sender from ? sender mail-followup-to reply-to from |
Command nosender is used to remove items from the sender
field list:
? sender mail-followup-to reply-to from ? nosender reply-to ? sender mail-followup-to from |
When used without arguments, this command clears the list:
? nosender Sender address is obtained from the envelope |
The incorporate (inc) command incorporates newly arrived
messages to the displayed list of messages. This is done automatically
before returning to mail command prompt if the variable
autoinc is set.
To run arbitrary shell command from mail command prompt, use
shell (sh) command. If no arguments are specified, the
command starts the user login shell. Otherwise, it uses its first
argument as a file name to execute and all subsequent arguments are
passed as positional parameters to this command. The shell
command can also be spelled as !.
Several commands discussed in the previous section save messages in
a disk file. The name of that file is either obtained from the
record variable (recording mail) or is derived from the
first recipient of the message (saving by name).
The following commands record mails:
mail
reply
Reply
The following commands save mail by name:
Copy
Save
Mail
followup
Followup
Saving mail by name is controlled by three mail variables:
outfolder, folder, and outfilename.
The first, outfolder, is a boolean variable which, when set,
enables saving mail by name. The folder variable defines a
directory where mail files are stored. Name of file in that directory
where the message will be saved is derived from the message
recipient2. This process is controlled by the outfilename
variable: if its value is ‘local’, the file is named by the local
part of the email (this is the default). If it is ‘domain’, the
domain part is used instead. Finally, if it’s value is ‘email’,
the entire email is used.
As a GNU extension, outfolder can be a string variable. In
that case its value names the directory to use instead of
folder.
The mailx variable, if set, disables GNU extensions. In this
case, outfolder is used as a boolean value, and file names are
derived from the local part of the email, ignoring the
outfilename value.
You can compose the message by simply typing the contents of it, line
by line. But usually this is not enough, you would need to edit
your text, to quote some messages, etc. Mail provides these
capabilities through compose escapes. The compose escapes
are single-character commands, preceded by special escape character,
which defaults to ‘~’. The combination escape character + command
is recognized as a compose escape only if it occurs at the beginning of
a line and the standard input is connected to a terminal. If the
escape character must appear at the beginning of a line, enter it
twice.
The actual escape character may be changed by setting the value of
escape mail variable (see Mail Variables).
There are several commands allowing you to quit the compose mode.
Typing the end-of-file character (‘C-D’) on a line alone finishes
compose mode and sends the message to its destination. The ‘C-D’
character looses its special meaning if ignoreeof mail variable
is set.
If mail variable dot is set, typing dot (‘.’) on a line
alone achieves the same effect as ‘C-D’ above.
Finally, using ‘~.’ escape always quits compose mode and sends out the composed message.
To abort composing of a message without sending it, type interrupt
character (by default, ‘C-C’) twice. This behavior is disabled
when mail variable ignore is set. In this case, you can use
‘~x’ escape to achieve the same effect.
The ‘~?’ escape prints on screen a brief summary of the available compose escapes. Please note, that ‘~h’ escape prompts for changing the header values, and does not give help.
If you are not satisfied with the message as it is, you can edit it
using a text editor specified either by EDITOR or by
VISUAL environment variables. The ‘~e’ uses the former,
and ‘~v’ uses the latter.
By default both escapes allow you to edit only the body of the
message. However, if the editheaders variable is set,
mail will load into the editor the complete text of
the message with headers included, thus allowing you to change
the headers as well.
To add new addresses to the list of message recipients, use ‘~t’ command, e.g.:
~t name1@domain.net name2
To add addresses to Cc or Bcc, use ‘~c’ or ‘~b’
escapes respectively.
To change the Subject header, use ‘~s’ escape, e.g.:
~s "Re: your message"
Finally, to edit all headers, type ‘~h’ escape. This will present
you with the values of To, Cc, Bcc, and
Subject headers allowing to edit them with normal text editing
commands.
If you are sending mail from within mail command mode, you can enclose the contents of any message sent to you by using ‘~m’ or ‘~M’ commands. Typing ‘~m’ alone will enclose the contents of the current message, typing ‘~m 12’ will enclose the contents of message #12 and so on.
The ‘~m’ uses retained and ignored lists when enclosing headers, the ‘~M’ encloses all header fields.
In both cases, the contents of indentprefix mail variable is
prepended to each line enclosed.
To append the contents of file filename to the message, type
~r filename
or
~< filename
The ‘~d’ escape is a shorthand for
~r dead.letter
The ‘~+’ escape attaches a file to the message. It takes one to three arguments. The first argument supplies the name of the file to attach:
~+ myfile.txt
The file will be attached with default content-type ‘application/octet-stream’, and encoding ‘base64’ (these can be altered by the --content-type and --encoding command line options, correspondingly).
Optional second argument defines the content type to be used instead of the default one. Optional third argument defines the encoding, e.g.:
~+ myfile.html text/html base64
To list the files attached so far, use the ‘~l’ escape:
~l multipart/mixed 1 myfile.html text/html base64
The first line of the output shows the content type of the message. Each subsequent line contains the ordinal number of the attachment, the name of the file, content-type and transfer encoding used.
The ‘~/’ escape toggles the content type bewteen ‘multipart/mixed’, and ‘multipart/alternative’. The new value of the content type is displayed on the screen.
The ‘~^’ escape removes attachments. Its argument is the number of the attachment to remove, e.g.:
~^ 1
The ‘~p’ escape types the contents of the message entered so far, including headers, on your terminal. You can save the message to an arbitrary file using ‘~w’ escape. It takes the filename as its argument.
To save you the effort of typing your signature at the end of each
message, you can use ‘~a’ or ‘~A’ escapes. If your signature
occupies one line only, save it to the variable sign and use
‘~a’ escape to insert it. Otherwise, if it is longer than one
line, save it to a file, store the name of this file in the
variable Sign, and use ‘~A’ escape to insert it into
the message.
Sometimes it is necessary to view the contents of another message, while composing. These two escapes allow it. Both take the message list as their argument. If they are used without argument, the contents of the current message is printed. The difference between ‘~f’ and ‘~F’ is that the former uses ignored and retained lists to select headers to be displayed, whereas the latter prints all headers.
The ‘~i’ escape enters the value of the named mail variable into the body of the message being composed.
You can execute a mail command from within compose mode using ‘~:’ or ‘~-’ escapes. For example, typing
~: from :t
will display the from lines of all tagged messages. Note, that executing
mail-sending commands from within the compose mode is not allowed.
An attempt to execute such a command will result in diagnostic message
“Command not allowed in an escape sequence” being displayed.
Also, when starting compose mode immediately from the shell
(e.g. running ‘mail address@domain’), most mail commands are
meaningless, since there is no mailbox to operate upon. In this case,
the only commands that can reasonably be used are: alias,
unalias, alternate, set, and unset.
The ‘~!’ escape executes specified command and returns you to
mail compose mode without altering your message. When used without
arguments, it starts your login shell. The ‘~|’ escape pipes the
message composed so far through the given shell command and replaces the
message with the output the command produced. If the command produced
no output, mail assumes that something went wrong and retains
the old contents of your message.
Multipart messages (or MIME, for short) can be used to send text in character sets other than ASCII, attach non-text files, send multiple parts in alternative formats, etc.
Technically speaking, the boolean variable mime
controls this feature. If it is set (see Setting and Unsetting the Variables), MIME will create MIME messages by default.
The variable can be set in the global or user configuration file
(see Mail Configuration Files), using the following command:
set mime
It can also be set from the command line, using the --mime option.
GNU mail automatically turns on the MIME mode, when it is
requested to send a non-plaintext message, or a message in character
set other than ASCII, when the encoding is specified, or when
attachments are given.
To send a message in another character set, specify it with the --content-type option:
mail --content-type 'text/plain; charset=utf-8'
The --encoding specifies the encoding to use:
mail --content-type 'text/plain; charset=utf-8' --encoding=base64
Its argument is any encoding supported by GNU mailutils. The two most often used encodings are ‘base64’ and ‘quoted-printable’.
To specify the charset from mail interactive section, enable
the “edit headers” mode (set editheaders) and add the
needed Content-Type header manually.
GNU mail also gives you a possibility to attach files to the
message being sent.
The simplest way to attach a file from command line is by using the --attach (-A) option. Its argument specifies the file to attach. For example, the following will attach the content of the file archive.tar:
$ mail --attach=archive.tar
By default, the content type will be set to ‘application/octet-stream’, and the attachment will be encoded using the ‘base64’ encoding. To change the content type, use the --content-type option. For example, to send an HTML attachment:
$ mail --content-type=text/html --attach=in.html
The --content-type option affects all --attach options that follow it, and the message body (if any). To change the content type, simply add another --content-type option. For example, to send both the HTML file and the archive:
$ mail --content-type=text/html --attach=in.html \
--content-type=application/x-tar --attach=archive.tar
To change the content type of the message body when sending a message with attachments, use the trailing --content-type option, i.e. the option not followed by another --attach option:
$ mail --content-type=text/html --attach=in.html \
--content-type=application/x-tar --attach=archive.tar \
--content-type=text/plain
This example adds two attachments with different content types and switched back to the ‘text/plain’ content type for the message body.
The encoding to use is set up by the --encoding option. As well as --content-type, this option affects all attachments supplied after it in the command line as well as the message body read from the standard input, until changed by the eventual next instance of the same option. Extending the above example:
$ mail --content-type=text/html --encoding=quoted-printable \
--attach=in.html \
--content-type=application/x-tar --encoding=base64 \
--attach=archive.tar
A trailing --encoding option sets the encoding of the message body.
Each attachment can also be assigned a description and a file name. Normally, these are the same as the file name supplied with the --attach option. However, you can change either or both of them using the --content-name and --content-filename, correspondingly. Both of these options affect only the next --attach (or --attach-fd, see below) option.
By default, the message will be assigned the content type ‘multipart/mixed’. To change it to ‘multipart/alternative’, use the --alternative command line option. Using this option also sets the ‘Content-Disposition’ header of each attached message to ‘inline’.
All the examples above will enter the usual interactive shell, allowing you to compose the body of the message. If that’s not needed, the non-interactive use can be forced by redirecting /dev/null to the standard input, e.g.:
$ mail --attach=archive.tar < /dev/null
This will normally produce a message saying:
mail: Null message body; hope that's ok
To suppress this message, unset the ‘nullbodymsg’ variable, as shown in the example below:
$ mail -E 'set nonullbodymsg' --attach=archive.tar < /dev/null
The option --attach=- forces mail to read the file
to be attached from the standard input stream. This option disables
the interactive mode and sets ‘nonullbodymsg’ implicitly, so that
the above example can be rewritten as:
$ mail --attach=- < archive.tar
Special option is provided to facilitate the use of mail
in scripts. The --attach-fd=N instructs the program to
read the data to be attached from the file descriptor N. The
above example is equivalent to:
$ mail --attach-fd=0 < archive.tar
Attachments created with this option have neither filename nor description set, so normally the use of --content-name and/or --content-filename is advised.
The option --skip-empty-attachments instructs mail
to skip creating attachments that would have zero-size body. This
option affects all attachments created by --attach and
--attach-fd options appearing after it in the command line.
It also affects the handling of the original message body. To cancel
its effect, use the --no-skip-empty-attachments option.
Here are some examples illustrating how it works.
First, consider the following command line
$ mail --attach=archive.tar </dev/null
Assume that archive.tar is not empty.
This will create a MIME message of two parts: the first part having ‘text/html’ type and empty body, and the second part of type ‘application/octet-stream’, with the content copied from the file archive.tar.
Now, if you do:
$ mail --attach=archive.tar --skip-empty-attachments </dev/null
then the created MIME message will contain only one part: that containing archive.tar.
If the file archive.tar has zero length, the resulting archive will still contain the ‘application/octet-stream’ part of zero length. However, if you place the --skip-empty-attachments option before --attach, then the produced message will be empty.
The following Perl program serves as an example of using
mail from a script to construct a MIME message on the fly.
It scans all mounted file systems for executable files that have
setuid or setgid bits set and reports the names of those files in
separate attachments. Each attachment is named after the mountpoint
it describes.
The script begins with the usual prologue stating the modules that will be used:
#!/usr/bin/perl use strict; use autodie;
Then global variables are declared. The ‘@rcpt’ array contains the email addresses of the recipients:
my @rcpt= 'root@example.com';
The ‘@cmd’ variable holds the mail command line. It
will be augmented for each file system. The initial value is set as
follows:
my @cmd = ('mail',
'-E set nonullbodymsg',
'--content-type=text/plain');
The find utility will be used to locate the files. The
script will start as many instances as there are mountpoints. Those
instances will be run in parallel and their standard output streams
will be connected to file descriptors passed to mail
invocation in --attach-fd options.
The descriptors will be held in ‘@fds’ array. This will prevent
them from being wiped out by the garbage collector. Furthermore, care
should be taken to ensure that the O_CLOEXEC flag be not set
for these descriptors. This sample script takes a simplistic approach:
it instructs Perl not to close first 255 descriptors when executing
another programs:
my @fds; $^F = 255;
The following code obtains the list of mount points:
open(my $in, '-|', 'mount -t nonfs,noproc,nosysfs,notmpfs');
while (<$in>) {
chomp;
if (/^\S+ on (?<mpoint>.+) type (?<fstype>.+) /) {
For each mountpoint, the find command line is constructed
and launched. The file descriptor is pushed to the ‘@fds’ array
to prevent it from being collected by the garbage collector:
open(my $fd, '-|',
"find $+{mpoint} -xdev -type f"
. " \\( -perm -u+x -o -perm -g+x -o -perm -o+x \\)"
. " \\( -perm -u+s -o -perm -g+s \\) -print");
push @fds, $fd;
Now, the mail command is instructed to create next
attachment from that file descriptor:
my $mpname = $+{mpoint};
$mpname =~ tr{/}{%};
push @cmd,
"--content-name=Set[ug]id files on $+{mpoint} (type $+{fstype})",
"--content-filename=$mpname.list",
'--attach-fd=' . fileno($fd);
}
}
close $in;
Finally, the emails of the recipients are added to the command line,
the standard input is closed to make sure mail won’t enter
the interactive mode and the constructed command is executed:
push @cmd, @rcpt; close STDIN; system(@cmd);
The ‘#’ character introduces an end-of-line comment. All characters until and including the end of line are ignored.
The ‘echo’ (‘ec’) command prints its arguments to stdout.
The command ‘source filename’ reads commands from the named file. Its minimal abbreviation is ‘so’.
The mail variables are set using ‘set’ (‘se’) command. The command takes a list of assignments. The syntax of an assignment is
Assign a string value to the variable. If string contains whitespace characters it must be enclosed in a pair of double-quote characters (‘"’)
Assign a numeric value to the variable.
Assign boolean True value.
Assign boolean False value.
Example:
? set askcc nocrt indentprefix="> "
This statement sets askcc to True, crt to
False, and indentprefix to “> ”.
To unset mail variables use ‘unset’(‘uns’) command. The command takes a list of variable names to unset.
To undo the effect of the previous example, do:
? unset askcc crt indentprefix
When used without arguments, both set or unset
list all currently defined variables. The form of this listing is
controlled by variable-pretty-print (varpp) variable. If
it is set, a description precedes each variable, e.g.:
# prompt user for subject before composing the message ask # prompt user for cc before composing the message askcc # output character set for decoded header fields charset="auto" # number of columns on terminal screen columns=80
If variable-pretty-print is not set, only the settings are
shown, e.g.:
ask askcc charset="auto" columns=80
A special command is provided to list all internal mail
variables:
variable [names...]
If used without arguments, it prints all known internal variables. If arguments are given, it displays only those internal variables that are listed in command line. For each variable, this command prints its name, data type, current value and a short description. For example:
? variable ask datefield ask, asksub Type: boolean Current value: yes prompt user for subject before composing the message datefield Type: boolean Current value: [not set] get date from the `Date:' header, instead of the envelope
Shell environment may be modified using ‘setenv’ (‘sete’) command. The command takes a list of assignments. The syntax of an assignment is:
If variable name does not already exist in the environment, then it is added to the environment with the value value. If name does exist, then its value in the environment is changed to value.
Delete the variable name from the environment (“unset” it).
The conditional statement allows to execute a set of mail commands
depending on the mode the mail program is in. The conditional
statement is:
if cond ... else ... endif
where ‘...’ represents the set of commands to be executed in each branch of the statement. cond can be one of the following:
True if mail is operating in mail sending mode.
True if mail is operating in mail reading mode.
True if stdout is a terminal device (as opposed to a regular file).
The conditional statements can be nested to arbitrary depth. The minimal abbreviations for ‘if’, ‘else’ and ‘endif’ commands are ‘i’, ‘el’ and ‘en’.
Example:
if t set crt prompt="& " else unset prompt endif if s alt gray@example.com gray@example.org set
mailFollowing variables control the behavior of GNU mail:
Default: True
Comment: Read-Only
Messages saved in mbox are appended to the end, rather than
prepended. This is the default and cannot be changed. This variable
exists only for compatibility with other mailx
implementations.
Default: False
If this variable is set, the contents of canceled letter is appended to the user’s dead.letter file. Otherwise it overwrites its contents.
Default: False
When set to True the user will be prompted to enter Bcc
field before composing the message.
Default: True
When set to True the user will be prompted to enter Cc
field before composing the message.
Default: True in interactive mode, False otherwise.
When set to True the user will be prompted to enter Subject
field before composing the message.
Default: True
Automatically incorporate newly arrived messages.
Default: False
Causes the delete command to behave like dp: after deleting a
message, the next one will be typed automatically.
Default: False
When set, every occurrence of ! in arguments to !
escape is replaced with the last executed command.
See Executing Shell Commands, for details on the ! escape.
Default: False
By default the date in a header summary is taken from the SMTP
envelope of the message. Setting this variable tells mail
to use the date from Date: header field, converted to
local time. Notice, that for messages lacking this field mail
will fall back to using SMTP envelope.
See fromfield.
Default: ‘auto’
The value of this variable is the character set used for input and
output operations. If the value is ‘auto’, mail will
try to deduce the name of the character set from the value of
LC_ALL environment variable. If the variable contains the
character set part (e.g. ‘nb_NO.utf-8’), it will be used.
Otherwise, mail will look up in its built-in database the
value of the character for this language/territory combination. If
LC_ALL is not set, the LANG environment variable is
inspected.
The value of charset controls both input and output
operations. On input, it is used to set the value of the
‘charset’ parameter in the ‘Content-Type’ MIME header, if
its value begins with ‘text/’ and the ‘charset’ parameter is
not present.
On output, it is used to display values of the header fields encodied using RFC 2047. If the variable is unset, no decoding is performed and the fields are printed as they are. Otherwise, they are recoded to that character set.
Default: Unset
Contains default shell command for pipe.
Default: Detected at startup by querying the terminal device. If this
fails, the value of environment variable COLUMNS is used.
This variable contains the number of columns on terminal screen.
Default: True in interactive mode, False otherwise.
The variable crt determines the minimum number of lines the body
of the message must contain in order to be piped through pager command
specified by environment variable PAGER. If crt is set
to a numeric value, this value is taken as the threshold. Otherwise,
if crt is set without a value, then the height of the terminal
screen is used to compute the threshold. The number of lines on
screen is controlled by screen variable.
Default: Unset
Sets mailutils debug level. If set to string, the value must be a valid Mailutils debugging specification. See Debug Statement, for a description.
If unset (i.e. set nodebug), clears and disables all debugging
information. If set to ‘true’ (i.e. set debug), sets
maximum debugging (‘<trace7’) on mailbox and its underlying
objects.
Default: ‘none’
This variable controls the way to represent characters that cannot be rendered using current character set. It can have three values:
Such characters are not printed at all. The conversion process stops at the first character that cannot be rendered.
The characters are displayed ‘as is’. Notice, that depending on your setup, this may screw-up your terminal settings.
Unprintable characters are represented by their octal codes. Printable ones are printed ‘as is’.
Default: False
If set, causes mail to interpret a period alone on a line as the
terminator of a message you are sending.
Default: False
When set, mail will include message headers in the text to
be the ~e and ~v escapes, thus allowing you to customize
the headers.
Default: False
If the mailbox is empty, mail normally prints ‘No mail
for user’ and exits immediately. If this option is set,
mail will start no matter is the mailbox empty or not.
Default: ‘~’
Current value of the command escape character.
Default: Unset
If set, the variable flipr swaps the meanings of reply
and Reply commands (see Replying).
Default: Unset
The name of the directory to use for storing folders of messages. If
unset, $HOME is assumed.
Default: True
By default the sender address is taken from the ‘From’ header.
Unsetting this variable tells mail to obtain it from the
SMTP envelope instead.
See datefield.
Default: True
Preserve personal parts (comments) of recipient addresses when replying to a message.
When unset, only emails will be used.
See Replying.
Default: True, unless started with --nosum (-N) option.
Whether to run headers command automatically after entering
interactive mode.
Default: ‘%>%a%4m %18f %16d %3l/%-5o %s’
Format string to use for the header summary. The ‘%’ character introduces a format specifier. The format specifier consists of optional alignment specifier (‘+’ or ‘-’ sign), optional output width and the specifier letter. Format specifiers are replaced on output with the corresponding piece of information from the message being described.
The ‘-’ character immediately following ‘%’ indicates that this field should be left aligned. The ‘+’ character indicates right alignment. Default alignment depends on the type of the specifier: the specifiers that produce numeric values (‘%l’, ‘%m’, and ‘%o’) are aligned to the right, whereas the ones producing string or date/time values are aligned to the left.
A number following ‘%’ or the alignment flag, indicates the field width.
Consider the ‘%m’ specifier as an example:
Print current message number. Take as much screen columns as necessary for output.
Print current message number. Use exactly 4 screen columns, truncating the output if it does not fit that width. Align the output to the right.
Same as above, but align to the left.
Valid format specifiers are:
Message attribute. One of the following letters, or a single horizontal space, if none of them applies:
| ‘M’ | the message was copied to the mailbox (mbox command) |
| ‘P’ | the message was preserved (hold command) |
| ‘*’ | the message was saved (save or Save) |
| ‘T’ | the message was tagged (tag) |
| ‘R’ | the message was read |
| ‘N’ | the message is new (was not seen) |
| ‘U’ | the message was seen, but wasn’t read |
The date when the message was received. It is determined from the message header defined by the ‘datefield’ variable (see datefield). If that variable is not set, or the requested header is not present in the message, the date from the envelope is used.
The output is formatted according to the following format specification (see Date/time Format String):
%a %b %e %H:%M
I.e.: abbreviated weekday name, abbreviated month name, day of the month as a decimal number, followed by hour and minutes. All names are displayed according to the current locale.
Same as ‘%d’, but the date is formatted according to the date/time format fmt. It is essentially a C ‘strftime’ format string, described in detail in Date/time Format String.
For example:
set headline="%4m %20D{%Y-%m-%dT%H:%M:%S}"
Note, that the opening ‘{’ must follow the format letter without any intervening whitespace. If fmt contains ‘{’, ‘}’, or ‘\’, these characters must be escaped with backslash (e.g. ‘\{’).
A simplified form of the ‘%D’ specifier. It is equivalent to
%D{%f}
where f is a single ‘strftime’ specifier letter. It can be preceded by ‘E’ or ‘O’, if the Single UNIX Specification allows such usage (see conversion specs), e.g. ‘%DOU’.
Notice, that ‘%D’ not followed by a valid time format in either of the above forms is treated as unknown specifier.
The email address of the message sender.
The number of lines of the message.
Message number.
The number of octets (bytes) in the message.
Message subject (if any).
Message subject (if any) in double quotes.
A ‘>’ for the current message, otherwise a space.
A ‘<’ for the current message, otherwise a space.
A ‘%’ character.
Default: False
Determines the location where to store the messages in state
‘read’ and (if the keepsave is also set) ‘saved’.
When set, these messages will be retained in the system mailbox.
When not set (the default), such messages will be stored in the user’s personal mailbox.
See read messages, and See saved messages, for a detailed information on how such messages are processed when the mailbox is being closed.
See keepsave, for the discussion of the keepsave variable.
Default: False
When set to True, mail will ignore keyboard interrupts
when composing messages. Otherwise an interrupt will be taken as a
signal to abort composing.
Default: False
Controls whether typing EOF character terminates the letter being composed.
Default: "\t" (a tab character).
String used by the ~m tilde escape for indenting quoted messages.
Default: False
If set, mail will expand aliases in the address header field
before entering send mode (see Composing Mail). By default, the
address header fields are left intact while composing, the alias
expansion takes place immediately before sending message.
Comment: Read-Only
Default: True
Truncate the user’s system mailbox when it is empty, instead of
removing it. This is the default and cannot be changed. This variable
exists only for compatibility with other mailx implementations.
Default: False
Controls whether saved messages should be retained. The location
where they will be retained is controlled by the hold variable
(see the hold variable).
This variable is in effect only when operating upon the user’s system mailbox.
See saved messages, for a detailed information on how the saved messages are processed when the mailbox is being closed.
Default: False
When set, enables mailx compatibility mode. This mode has the following effects:
mail will ask
for Cc and Bcc addresses after composing the body.
The default behavior is to ask for these values before composing
the body.
mail
will exit with zero status. By default it exits with zero status only
if the message was sent successfully.
outfolder variable is treated as boolean.
see outfolder.
outfilename is ignored (assumed to be
‘local’). see outfilename.
folder and record variables are
assumed relative to the home directory, unless they begin with
‘/’, ‘~’, or ‘+’.
sendmail variable does not begin with
a scheme specification, ‘sendmail:/’ is assumed. See sendmail mail variable.
Default: True
This variable controls operation of decode command. If
it is unset, decode will not attempt any interpretation
of the content of message parts. Otherwise, if metamail
is set to true, decode will use internal metamail
support to interpret message parts. Finally, if metamail
is assigned a string, this string is treated as command line of
the external metamail command which will be used to
display parts of a multipart message. For example:
# Disable MIME interpretation: set nometamail # Enable built-in MIME support: set metamail # Use external program to display MIME parts: set metamail="metamail -m mail -p"
Default: False
If set, this variable instructs mail to compose MIME
messages.
It can be set from the command line using --mime option.
Default: Unset
By default mail asks for confirmation before running
interpreter to view a part of the multi-part message. If this variable
is set, its value is treated as a comma-separated list of MIME types
for which no confirmation is needed. Elements of this list may include
shell-style globbing patterns, e.g. setting
set mimenoask=text/*,image/jpeg
will disable prompting before displaying any textual files, no matter what their subtype is, and before displaying files with type ‘image/jpeg’.
Default: False
Usually, when an alias is expanded that contains the sender, the sender is removed from the expansion. Setting this option causes the sender to be included in the group.
Comment: Read-Only
Default: The name of current operation mode.
This variable keeps the name of the current operation mode. Its possible values are:
The program is started with the --headers (-H) command line option (see Invoking Mail).
The program is started with the --exist (-e) command line option (see Invoking Mail).
The program is started with the --print (-p) command line option (see Invoking Mail).
The program operates in read mode. This is the default.
The program operates in send mode. This means it was given one or more recipient addresses in the command line.
Default: True
Controls whether mail accepts messages with an empty
body. The default value, true, means such messages are sent,
and a warning (traditionally saying ‘Null message body; hope
that's ok’) is displayed. The text of the warning can be set using
nullbodymsg variable (see below).
If nullbody is unset, mail will silently ignore such
messages. This can be useful in crontab files, to avoid sending
mails when nothing important happens. For example, the crontab
entry below will send mail only if the utility some-prog
outputs something on its standard output or error:
*/5 * * * * some-prog 2>&1 | \ /bin/mail -E'set nonullbody' -s 'Periodic synchronization'
Default: ‘Null message body; hope that's ok’
Text of the warning displayed by mail before
sending an empty message. When available, the translation of
this text, in accordance with the current locale, is displayed.
Unsetting this variable disables the warning.
Default: Unset
This variable is not used. It exists for compatibility with other
mailx implementations and for future use.
Comment: Three-state: ‘local’, ‘email’, ‘domain’.
Default: ‘local’
Defines the algorithm to convert the recipient email to the name of
the file used to record outgoing messages to that recipient. This
affects the following commands: Copy, Save, Mail,
followup, and Followup. The following values are allowed:
localLocal part of the email address is taken as the file name. This is the default.
emailEntire email is takes as the file name.
domainDomain part of the email is used as the file name.
Default: Unset
When set as boolean, causes the files used to record outgoing messages
to be located in the directory specified by the folder variable
(unless the pathname is absolute).
If set to a string value, names the directory where to store these files.
This variable affects the following commands: Copy,
Save, Mail, followup, and Followup.
In mailx compatibility mode, only boolean value is allowed. see mailx mail variable.
Default: Unset
If set, the pipe command will emit a linefeed
character after printing each message.
Comment: Read-Only
Default: PID of the process.
PID of the current mail process.
Default: "? "
Contains the command prompt sequence.
Default: Unset
This variable is not used. It exists for compatibility with other
mailx implementations and for future use.
Default: False, unless started with --quit (-q) option.
When set, causes keyboard interrupts to terminate the program.
Default: True, unless started with --norc (-N) option.
When this variable is set, mail will read the system-wide
configuration file upon startup. See Mail Configuration Files.
Default: False
When set, mailboxes are opened in readonly mode. In this mode, any
mail commands that alter the contents of the mailbox are
disabled. These commands include, but are not limited to:
delete, save and mbox.
Default: Unset
When set, outgoing messages produced by the following commmands will
be saved to the named file: mail, reply, Reply.
See also outfolder and outfilename.
Default: True
When set, mail will expand aliases recursively.
Default: True.
If set, enables the use of regular expressions in ‘/.../’ message specifications.
Default: ‘Re: ’
Sets the prefix that will be used when constructing the subject line of a reply message.
Default: ‘^re: *’
Sets the regular expression used to recognize subjects of reply
messages. If the Subject header of the message matches this
expression, the value of replyprefix will not be prepended to
it before replying. The value should be a POSIX extended regular
expression. The comparison is case-insensitive.
For example, to recognize usual English, Polish, Norwegian and German reply subject styles, use:
set replyregex="^(re|odp|aw|ang)(\\[[0-9]+\\])?:[[:blank:]]"
(Notice the quoting of backslash characters).
Default: unset
Sets the return email address to use when sending messages. If unset, return address is composed from the current user name and the host name.
Default: True.
When set, the aborted messages will be stored in the user’s
dead.file. See also appenddeadletter.
Default: Detected at startup by querying the terminal device. If this
fails, the value of environment variable LINES is used.
This variable contains the number of lines on terminal screen. See also crt.
Default: ‘sendmail:/usr/lib/sendmail’
Contains URL of the mail transport agent. If the value begins with a scheme specifier, it must be one of the mailer URL schemes supported by mailutils (see mailer URL). Otherwise, if not in mailx compatibility mode, the value starting with directory separator (‘/’) is treated as the external command that will be started as is and the composed message will be piped to its standard input.
In mailx compatibility mode (see mailx mail variable), the ‘sendmail:’ prefix is assumed.
Default: Unset
This variable is not used. It exists for compatibility with other
mailx implementations and for future use.
Default: Unset
Contains the filename holding users signature. The contents of this
file is appended to the end of a message being composed by ~A
escape.
Default: Unset
Contains the user’s signature. The contents of this variable is appended
to the end of a message being composed by ~a escape. Use
Sign variable, if your signature occupies more than one line.
Default: Unset
If this variable is set, the print command will include the
SMTP envelope in its output.
Default: Unset
If this variable is set, mail will show To: addresses
instead of From: for all messages that come from the user that
invoked the program.
Default: Unset
Contains default subject line. This will be used when asksub is
off.
Default: 5
Number of lines to be displayed by top and Top commands.
Default: False
If this variable is set, the listing output by set contains short
descriptions before each variable. See Setting and Unsetting the Variables.
Default: False
Setting this variable enables strict control over variable
settings. In this mode, mail refuses to set read-only
variables. Also, if the user is trying to set an unknown variable,
mail prints a warning.
Default: False
When set, the actual delivery of messages is displayed on the user’s terminal.
Default: True
Controls whether the ‘User-Agent’ header should be added to outgoing messages. The default value of this header is
User-Agent: mail (GNU Mailutils 3.14)
This header is retained for compatibility with previous releases of
GNU Mailutils. Since version 3.13 it is an alias for
useragent.
After processing the usual Mailutils configuration files
(see configuration), mail reads the contents of the two
command files: the system-wide command file, and the user’s command
file. Each line read from these files is processed like a usual
mail command.
When run with --norc (-N) option, mail does
not read the contents of system-wide configuration file. The user’s
file, if it exists, is always processed.
The user’s configuration file is located in the user’s home directory and is named .mailrc. The location and name of the system-wide configuration file is determined when configuring the package via --with-mail-rc option. It defaults to sysconfdir/mail.rc.
messages — Count the Number of Messages in a MailboxMessages prints on standard output the number of messages
contained in each folder specified in command line. If no folders
are specified, it operates upon user’s system mailbox. For each
folder, the following output line is produced:
Number of messages in folder: number
where folder represents the folder name, number represents the number of messages.
The following configuration file statements affect the behaviour of
messages:
| Statement | Reference |
|---|---|
| debug | See debug statement. |
| tls | See tls statement. |
| mailbox | See mailbox statement. |
| locking | See locking statement. |
In addition to the common mailutils options (see Common Options), the program accepts the following command line options:
Be quiet. Display only number of messages per mailbox, without leading text.
movemail — Moves Mail from the User Maildrop to the Local FileThe purpose of movemail, as its name implies, is to move mail
from one location to another. For example, the following invocation:
movemail /var/mail/smith INBOX
moves messages from file /var/mail/smith to file INBOX.
The program was initially intended as a replacement for
movemail from GNU Emacs. The movemail program is
run by Emacs Rmail module. See Rmail in Reading Mail
with Rmail, for detailed description of Rmail interface.
Mailutils version of movemail is fully
backward-compatible with its Emacs predecessor, so it should run
flawlessly with older versions of Emacs. Emacs versions
starting from 22.1 contain improved Rmail interface and
are able to take advantage of all new features mailutils
movemail provides.
Apart from that use, movemail proved to be a useful tool for
incorporating mail from remote mailboxes into the local one. See
Fetching
Mail with Movemail, for a detailed discussion with usage recipes.
The following configuration file statements affect the behavior of
movemail:
If bool is ‘true’, do not remove messages from the source mailbox.
If bool is ‘true’, reverse message sorting order.
If bool is ‘true’, output information used by Emacs rmail interface.
Continue moving messages after errors. By default,
mailfromd exits immediately if it cannot copy a message.
Set program identifier, i.e. a string which will prefix all diagnostic messages issued by the program. By default, program name is used.
The fmt is a format string that may contain references to the following variables (see Variables):
prognameThe program name.
sourceURL of the source mailbox.
source_userUser part of the source mailbox URL.
source_hostHost part of the source mailbox URL.
source_pathPath part of the source mailbox URL.
destURL of the destination mailbox
dest_userUser part of the destination mailbox URL.
dest_hostHost part of the destination mailbox URL.
dest_pathPath part of the destination mailbox URL.
Setting program-id may be necessary if several movemail
instances are run simultaneously (e.g. invoked from a script) to
discern between the instances. For example:
program-id "${progname}: ${source} => ${dest}"
Avoid copying the message if a message with the same UIDL already exists in the destination mailbox.
Set verbosity level.
Define list of methods for setting ownership of the destination mailbox. The method-list argument can contain the following elements:
Copy owner UID and GID from the source mailbox. This method works only with local mailboxes, i.e.: ‘mbox’ (UNIX mailbox), ‘maildir’ and ‘mh’.
Get owner name from the source mailbox URL and obtain UID and GID for this user using mailutils authorization methods.
Set supplied uid and gid. If gid is not supplied, it is read from the /etc/passwd record for this UID.
Make destination mailbox owned by user.
Defines upper limit on the number of moved messages. Movemail will stop after transferring count messages.
By default, the number of messages is not limited.
Defines what to do if an error occurs when transferring a message. actions is a list of one or more of the following keywords:
Abort the transfer and terminate the program. This is the default action.
Skip to the next message.
Delete the affected message.
Count this message as processed.
Each keyword can be prefixed with ‘no’ to reverse its meaning.
The following standard Mailutils statements are supported:
| Statement | Reference |
|---|---|
| debug | See debug statement. |
| tls | See tls statement. |
| mailbox | See mailbox statement. |
| locking | See locking statement. |
| pam | See pam statement. |
| sql | See sql statement. |
| virtdomain | See virtdomain statement. |
| radius | See radius statement. |
| ldap | See ldap statement. |
| auth | See auth statement. |
|
Editor’s note:
The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised. |
movemail [option...] inbox destfile [password]
The first argument, inbox, is the url (see Mailbox) of
the source mailbox. The second argument, destfile, traditionally
means destination file, i.e. the UNIX mailbox to copy messages
to. However, mailutils movemail extends the meaning of this
parameter. You may actually specify any valid url as
destfile parameter.3.
For compatibility with older implementations of movemail,
the source argument can also have the form:
po:username[:pop-server]
where pop-server is the IP address or hostname of a POP3 server to connect to and username is the name of the user on that server. The password is then supplied by the third argument.
It is equivalent to the following URL:
pop://username[:password]@pop-server
In fact, whenever source refers to a remote mailbox, the password argument can be used to pass the password. However, the safer ticket method is of course preferred.
Options are one or more of the following:
Output information used by Emacs rmail interface.
Try to continue after errors.
Process at most count messages.
Enable biff notification.
What to do on errors. See onerror statement, for a description of kw.
Control mailbox ownership. modelist is a comma-separated list of one or more ownership change methods. See mailbox-ownership-methods, for a description of available methods.
This option is useful only when running movemail as root.
Don’t remove transferred messages from the source mailbox.
Set program identifier for diagnostics (default: the program name). See movemail-program-id, for a description of its argument.
Reverse the order of retrieved messages.
Use UIDLs to avoid downloading the same message twice.
Increase verbosity level.
The common options are also understood (see Common Options).
readmsg — Extract Messages from a FolderThe readmsg utility extracts messages from a mailbox
according to the criteria specified in the command line. These
criteria are:
readmsg 1 3 0
extracts three messages from the folder: the first, the third, and the last.
readmsg staff meeting
extracts the message which contains the words ‘staff meeting’.
Note that it will not match a message containing ‘Staff Meeting’
– the matching is case sensitive by default. This can changed using
the -i (--ignorecase) option. Two more options are
provided to control the matching algorithm: the -g
(--glob) option instructs readmsg to treat
arguments as shell globbing patterns and the -r
(--regex) option instructs it to treat them as POSIX extended
regular expressions. Needless to say, when using any of the two latter
options, you should pay attention to escape the matching pattern to
prevent it from being interpreted by the shell. E.g.:
readmsg --regex 'staff.*meeting'
Unless requested otherwise, only the first message that matches the pattern is printed.
At least one command line argument or one informational option must be
present in readmsg invocation. Informational options are:
--help (-?), --usage, and
--version (-V).
readmsg.If a pattern is used for selection, show all messages that match pattern by default only the first one is presented.
Display mailbox debugging information.
Look for messages containing exactly the words given as arguments. This is the default. Other options changing this behavior are: --glob, --regex, and --ignorecase.
Specified the default mailbox.
Treat non-option arguments as shell globbing patterns. For example, to select the first message with words ‘morning’ and ‘coffee’ with anything bewteen them:
readmsg --glob 'morning*coffee'
(notice quoting, which prevents the shell from interpreting the ‘*’ prematurely).
Show the entire header and ignore the weedlist.
Ignore the case of letters when looking for matching messages. E.g.:
readmsg --glob --ignorecase 'morning*coffee'
Do not print the message header.
Put form-feed (Control-L) between messages instead of newline.
Treat non-option arguments as POSIX extended regular expressions.
A whitespace or coma separated list of header names to show per message. Default is --weedlist="From Subject Date To CC Apparently-".
See also Common Options.
readmsg.Following configuration statements affect the behavior of
readmsg:
If bool is ‘true’, display entire headers.
Set the weedlist. The str argument is a string, containing a list of header names, separated by whitespace, commands or colons. This corresponds to the --weedlist command line option (see –weedlist).
If bool is ‘true’, exclude all headers.
If bool is ‘true’, output formfeed character between messages.
Set the URL of the mailbox folder to read.
If bool is ‘true’, print all messages matching pattern, not only the first.
| Statement | Reference |
|---|---|
| debug | See Debug Statement. |
| tls | See TLS Statement. |
| mailbox | See Mailbox Statement. |
| locking | See Locking Statement. |
decodemail – Decode multipart messagesThe decodemail utility is a filter program that reads
messages from the input mailbox, decodes “textual” parts of each
multipart message from a base64- or quoted-printable encoding to an
8-bit or 7-bit transfer encoding, and stores the processed messages in
the output mailbox. All messages from the input mailbox are stored in
the output, regardless of whether a change was made.
The message parts deemed to be textual are those whose ‘Content-Type’ header matches a predefined, or user-defined, mime type pattern. In addition, encoded pieces of the ‘From:’, ‘To:’, ‘Subject:’, etc., headers are decoded.
For example, decodemail makes this transformation:
Subject: =?utf-8?Q?The=20Baroque=20Enquirer=20|=20July=202020?= ⇒ Subject: The Baroque Enquirer | July 2020
The built-in list of textual content type patterns is:
text/* application/*shell application/shellscript */x-csrc */x-csource */x-diff */x-patch */x-perl */x-php */x-python */x-sh
These strings are matched as shell globbing patterns (see glob in glob(7) manual page).
More patterns can be added to this list using the
mime.text-type configuration statement.
See mime statement, for a detailed discussion, and the
configuration section below for a simple example.
When processing old mesages you may encounter ‘Content-Type’ headers whose value contains only type, but no subtype. To match such headers, use the pattern without ‘/whatever’ part. E.g. ‘text/*’ matches ‘text/plain’ and ‘text/html’, but does not match ‘text’. On the other hand, ‘t*xt’ does not match ‘text/plain’, but does match ‘text’.
Optionally, the decoded parts can be converted to another character set. By default, the character set is not changed.
decodemail.Usually, the utility is invoked as:
decodemail inbox outbox
where inbox and outbox are file names or URLs of the input and output mailboxes, correspondingly. The input mailbox is opened read-only and will not be modified in any way. In particular, the status of the processed messages will not change. If the output mailbox does not exist, it will be created. If it exists, the messages will be appended to it, preserving any original messages that are already in it. This behavior can be changed using the -t (--truncate) option, described below.
The two mailboxes can be of different types. For example you can read input from an imap server and store it in local ‘maildir’ box using the following command:
decodemail imap://user@example.com maildir:///var/mail/user
Both arguments can be omitted. If outbox is not supplied, the resulting mailbox will be printed on the standard output in Unix ‘mbox’ format. If inbox is not supplied, the utility will open the system inbox for the current user and use it for input.
A consequence of these rules is that there is no simple way to read
the input mailbox from standard input (the input must be seekable).
If you need to do this, the normal procedure would be to save what
would be standard input in a temporary file and then give that file as
decodemail’s input.
The following command line options modify the decodemail
behavior:
Convert all textual parts from their original character set to the specified charset.
Convert all textual parts from their original character set to the
current character set, as specified by the LC_ALL or LANG
environment variable.
Do not convert character sets. This is the default.
If the output mailbox exists, truncate it before appending new messages.
Keep the existing messages in the output mailbox intact. This is the default.
Additionally, the Common Options are also understood.
decodemail.The following common configuration statements affect the behavior of
decodemail:
| Statement | Reference |
|---|---|
| mime | See mime statement. |
| debug | See Debug Statement. |
| mailbox | See Mailbox Statement. |
| locking | See Locking Statement. |
Notably, the mime statement can be used to extend the list of
types which are decoded. For example, in the file ~/.decodemail
(other locations are possible, see configuration), you could have:
# base64/qp decode these mime types also:
mime {
text-type "application/x-bibtex";
text-type "application/x-tex";
}
Since the list of textual mime types is open-ended, with new types being used at any time, we do not attempt to make the built-in list comprehensive.
decodemail.The principal use envisioned for this program is to decode messages in batch, after they are received.
Unfortunately, some mailers prefer to encode messages in their
entirety in base64 (or quoted-printable), even when the content is
entirely human-readable text. This makes straightforward use of
grep or other standard commands impossible. The idea is for
decodemail to rectify that, by making the message text
readable again.
Besides personal mail, mailing list archives are another place where such decoding can be useful, as they are often searched with standard tools.
It is generally not recommended to run decodemail within a
mail reader (which should be able to do the decoding itself), or
directly in a terminal (since quite possibly there will be 8-bit
output not in the current character set).
Although the output message from decodemail should be
entirely equivalent to the input message, apart from the decoding, it
is generally not identical. Because decodemail parses the
input message and reconstructs it for output, there are usually small
differences:
decodemail looks at the
actual content of the text and outputs
‘Content-Transfer-Encoding:’ accordingly.
SomeHeader: someextremelylongvaluethatcannotbebroken
If a discrepancy is created which actually affects message parsing or reading, that’s most likely a bug, and please report it. Naturally, please send an exact input message to reproduce the problem.
sieve|
Editor’s note:
The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised. |
Sieve is a language for filtering e-mail messages at time of final delivery, described in RFC 3028. GNU Mailutils contains stand-alone sieve interpreter, which is described in detail below.
The sieve interpreter sieve allows you to apply Sieve scripts to
arbitrary number of mailboxes. GNU sieve implements a superset
of the Sieve language as described in RFC 3028. See Sieve Language,
for a description of the Sieve language. See GNU Extensions, for a
discussion of differences between the GNU implementation of Sieve and
its standard.
sieveThe sieve invocation syntax is:
sieve [options] script
Normally, script is the name of the disk file with the Sieve script. If script is a single dash, the script is read from the standard input. If the -E (--expression) option is given, script is taken to be the sieve script text.
where script denotes the filename of the sieve program to parse, and options is one or more of the following:
Compile script and exit.
Clear Sieve library path. See also clear-library-path.
Clear Sieve include path. See also clear-include-path.
Specify debug flags. The flags argument is a sequence of one or more of the following letters:
| ‘g’ | Enable main parser traces |
| ‘T’ | Enable mailutils traces |
| ‘P’ | Trace network protocols |
| ‘t’ | Enable sieve trace |
| ‘i’ | Trace the program instructions |
Compile the script, dump disassembled code on standard output and exit.
Set sieve environment variable name to the value.
Override the user email address. This is useful for reject and
redirect actions. By default, the user email address is deduced
from the user name and the full name of the machine where
sieve is executed. See also email.
Treat the script argument as Sieve program text.
Append directory dir to the list of directories searched for include files. See also include-path.
Mailbox to sieve (defaults to user’s system mailbox). See also mbox-url.
Keep on going if execution fails on a message. See also keep-going.
Append directory dir to the list of directories searched for library files. See also library-path.
Add dir to the beginning of the list of directories searched for library files.
Print source location along with action logs (default).
Define the URL of the default mailer.
Dry run: do not execute any actions, just print what would be done.
Do not prefix diagnostic messages with the program name.
Ticket file for mailbox authentication. See also ticket.
Set Sieve variable name. This option automatically inserts ‘require "variables"’ at the top of the script.
Log all actions executed. See also verbose.
See also Common Options.
The behavior of sieve is affected by the following
configuration statements:
| Statement | Reference |
|---|---|
| debug | See debug statement. |
| tls | See tls statement. |
| mailbox | See mailbox statement. |
| locking | See locking statement. |
| logging | See logging statement. |
| mailer | See mailer statement. |
The following statements configure sieve-specific features:
This block statement configures search paths sieve uses to
locate its loadable modules. See Require Statement, for a detailed
information about loadable modules.
This statement may contain the following sub-statements:
If bool is ‘true’, clear library search path.
If bool is ‘true’, clear include search path.
Add directories to sieve library search path. Argument is a
string containing a colon-separated list of directories.
Add directories to the beginning if the library search path. Argument is a string containing a colon-separated list of directories.
Add directories to the include search path. Argument is a string containing a colon-separated list of directories.
If bool is ‘true’, do not abort if execution of a Sieve script fails on a particular message.
Sets URL of the mailbox to be processed.
Sets the name of the ticket file for user authentication.
Sets Sieve debug flags. See Logging and Debugging, for a detailed description.
If bool is ‘true’, log all executed actions.
If bool is ‘true’, print source locations along with action
logs. This statement takes effect only if verbose true is also
set.
Set user e-mail address. This is useful for reject and
redirect actions. By default, the user email address is deduced
from the user name and the full name of the machine where sieve is
executed.
The default behavior of sieve is to remain silent about
anything except errors. However, it is sometimes necessary to see
which actions are executed and on which messages. This is particularly
useful when debugging the sieve scripts. The --verbose
(-v) option outputs log of every action executed.
Option --debug allows to produce even more detailed debugging information. This option takes an argument specifying the debugging level to be enabled. The argument can consist of the following letters:
This flag enables sieve tracing. It means that every test will be logged when executed.
This flag enables debugging of underlying mailutils library.
Trace network protocols: produces log of network transactions executed while running the script.
Enable main parser traces. This is useful for debugging the sieve grammar.
Trace the program instructions. It is the most extensive debugging level. It produces the full execution log of a sieve program, showing each instruction and states of the sieve machine. It is only useful for debugging the code generator.
Note, that there should be no whitespace between the short variant of the option (-d), and its argument. Similarly, when using long option (--debug), its argument must be preceded by equal sign.
If the argument to --debug is omitted, it defaults to ‘TPt’.
Option --dump produces the disassembled dump of the compiled sieve program.
By default sieve outputs all diagnostics on standard error and verbose
logs on standard output. This behaviour is changed when
--log-facility is given in the command line (see logging).
This option causes sieve to output its diagnostics to
the given syslog facility.
sieveThe basic set of sieve actions, tests and comparators may be extended
using loadable extensions. The usual require mechanism is used for
that.
When processing arguments for require statement, sieve
uses the following algorithm:
LTDL_LIBRARY_PATH.
library-path-prefix configuration
statement (see library-path-prefix).
library-path statement (see library-path) in Sieve configuration file.
#searchpath Sieve directive (see #searchpath).
LD_LIBRARY_PATH).
The value of LTDL_LIBRARY_PATH and LD_LIBRARY_PATH must be
a colon-separated list of absolute directories, for example,
‘"/usr/lib/mypkg:/lib/foo"’.
In any of these directories, sieve first attempts to find
and load the given filename. If this fails, it tries to append the
following suffixes to the file name:
sieve executes its
initialization function (see below) and again looks up the name
in the symbol table. If found, search terminates successfully.
sieve then displays
the following diagnostic message:
source for the required action NAME is not available
guimb — A Mailbox Scanning and Processing LanguageGuimb is an experimental tool that iterates over messages in
a mailbox (or several mailboxes), applying a Scheme function to each
of them.
A user-defined scheme module that supplies the function to apply is specified using the --source or --file option. The module must define at least the following function:
Processes message msg. This function can alter the message using Guile primitives supplied by mailutils.
The following function definitions are optional:
If defined, this function is called after guimb has finished
processing the command line. args is a list of unconsumed
command line arguments.
The function is intended to provide a way of configuring the module from the command line.
If defined, this function is called after all mailboxes have been processed.
In the following example we define a module that prints
information about each message is the input mailbox, in a way similar
to frm utility:
(define-module (frm)
:export (guimb-message))
(use-modules (mailutils mailutils))
(define (guimb-message msg)
(display (mu-message-get-sender msg))
(display " ")
(display (mu-message-get-header msg "subject"))
(newline))
The modules are looked up in directories listed in the global variable
%load-path. New directories can be added to that variable on
the fly using the -L (--load-path) option. For
example, if the sample module above was saved in a file
frm.scm somewhere in the load path, it can be applied to the
current user inbox by running the following command:
guimb --file frm
The Scheme module that defines message processing functions is given via the following options:
Load Scheme code from module.
This option stops further argument processing, and passes all
remaining arguments as the value of args argument to the
guimb-getopt function, if it is defined.
Load Scheme source code from module. The remaining arguments are processed in the usual way. When using this option, you can pass additional options and or arguments to the module by enclosing them in -{ and -} options (see Passing Options to Scheme).
An experimental option is provided, that evaluates a supplied Scheme expression right after loading the module:
Evaluate scheme expression.
There are four basic ways of passing mailboxes to guimb.
guimb [options] [mailbox...]The resulting mailbox is not saved, unless the user-supplied scheme program saves it.
guimb [options] --mailbox defmboxThe contents of defmbox is processed and is replaced with the resulting mailbox contents. Useful for applying filters to user’s mailbox.
guimb [options] --mailbox defmbox mailbox [mailbox...]The contents of specified mailboxes is processed, and the resulting mailbox contents is appended to defmbox.
guimb [options] --user username [mailbox...]The contents of specified mailboxes is processed, and the resulting
mailbox contents is appended to the user’s system mailbox. This makes
it possible to use guimb as a mail delivery agent.
If no mailboxes are specified in the command line, guimb reads
and processes the system mailbox of the current user.
Sometimes it is necessary to pass some command line options to the scheme procedure. There are three ways of doing so.
When using --source (-s) option, the rest of the
command line following the option’s argument is passed as the
args argument to the guimb-getopt function, if such
function is defined. This allows for making guimb scripts executable
by the shell. If your system supports ‘#!’ magic at the start of
scripts, add the following two lines to the beginning of your script
to allow for its immediate execution:
#! /usr/local/bin/guimb -s !#
(replace ‘/usr/local/bin/’ with the actual path to the guimb).
Otherwise, if you use the --file option, the additional arguments can be passed to the Scheme program -g (--guile-arg) command line option. For example:
guimb --guile-arg -opt --guile-arg 24 --file progfile
In this example, the guimb-getopt function will get the
following argument
( '-opt' 24 )
Finally, if there are many arguments to be passed to Scheme, it is more convenient to enclose them in -{ and -} escapes:
guimb -{ -opt 24 -} --file progfile
This is a short summary of the command line options available to
guimb.
Start with debugging evaluator and backtraces.
Execute given Scheme expression.
Insert dir at the beginning of the %load-path list. The
argument is either a single directory name, or a list of such names,
delimited by ‘:’ characters.
Set path to the mailspool directory
Read Scheme program from progfile.
Append arg to the command line passed to Scheme program.
Pass all command line options enclosed between -{ and -} to Scheme program.
Set default mailbox name.
Act as local MDA for user name.
Display help message.
Display program version.
GNU local mail delivery agent reads a message from its standard input
and delivers it to one or more local recipients listed in the command
line. When we speak about local recipients, we mean that these
are system users that are known to the system that runs mda.
However, the mailboxes of these users can be local as well as remote
ones. mda is able to deliver mail to any mailbox format,
supported by GNU Mailutils. These formats, among others, include
‘smtp://’, ‘prog://’ and ‘sendmail://’ which are
equivalent to forwarding a message over SMTP to a remote
node.
Mda is also able to process incoming messages using
Sieve, Scheme or Python scripts and, based on results of this
processing, to take a decision on whether to actually deliver and
where to deliver them. Due to its extensive scripting facilities,
mda offers much more flexibility than other popular
MDAs.
mda with Sendmail.When used with Sendmail, mda must be invoked from the local
mailer definition in the sendmail.cf file. The flags
‘lswS’ must be set for the mailer. These mean: the mailer is
local, quote characters should be stripped off the address before
invoking the mailer, the user must have a valid account on this
machine and the userid should not be reset before calling the mailer.
Additionally, the ‘fn’ flags may be specified to allow
mda to generate the usual ‘From ’ envelope instead
of the one supplied by sendmail.
If you wish to use mda with non-local authentication,
such as SQL or LDAP, you also need to remove the
‘w’ flag, since in that case the user is not required to have a
valid account on the machine that runs sendmail.
Here is an example of mailer definition in sendmail.cf
Mlocal, P=/usr/local/sbin/mda,
F=lsDFMAw5:/|@qSPfhn9,
S=EnvFromL/HdrFromL, R=EnvToL/HdrToL,
T=DNS/RFC822/X-Unix,
A=mail $u
To define local mailer in ‘mc’ source file, it will suffice to set:
define(`LOCAL_MAILER_PATH', `/usr/local/sbin/mda') define(`LOCAL_MAILER_ARGS', `mail $u')
mda with Exim.Using mda with Exim is quite straightforward. The
following example illustrates the definition of the appropriate transport
and director in exim.conf:
# transport mda_pipe: driver = pipe command = /usr/local/sbin/mda $local_part return_path_add delivery_date_add envelope_to_add # director mda: driver = localuser transport = mda_pipe
mda with MeTA1.MeTA1 (http://meta1.org) communicates with the delivery agent
using LMTP. Instead of using mda you will have to
start the LMTP daemon lmtpd and configure MeTA1 to
communicate with it. See MeTA1-lmtpd, for details.
Mailbox quota is a limit on the size of the mailbox. When a
mailbox size reaches this limit, mda stops accepting
messages for this recipient and returns an error condition to the
sender. The error code is accompanied by the following error message:
user: mailbox quota exceeded for this recipient
Furthermore, if accepting the incoming message would make the mailbox size exceed the quota, such a message will be rejected as well. In this case, the error message is:
user: message would exceed maximum mailbox size for this recipient
In both cases, the default return code will be ‘service
unavailable’ (corresponding to the SMTP return code
‘550’), unless the following statement is present in the
maidag configuration file:
quota {
exit-tempfail yes;
}
in which case a temporary error will be returned.
The mailbox quota can be retrieved from the following sources:
To use DBM quota database, GNU Mailutils must
be compiled with one of the following command line options:
--with-gdbm, --with-berkeley-db, --with-ndbm,
--with-tokyocabinet, or --with-kyotocabinet.
Examine the output of mda --show-config-options, if not sure.
The quota database should have the following structure:
Key represents the user name. Special key ‘DEFAULT’ means default quota value, i.e. the one to be used if the user is not explicitly listed in the database.
Mailbox quota for this user. If it is a number, it represents the maximum mailbox size in bytes. A number may optionally be followed by ‘kb’ or ‘mb’, meaning kilobytes and megabytes, respectively.
A special value ‘NONE’ means no mailbox size limit for this user.
Here is an example of a quota database in text form:
# Default quota value: DEFAULT 5mb # Following users have unlimited mailbox size root NONE smith NONE # Rest of users plog 26214400 karin 10mB
To use the DBM quota database, specify its absolute name using
the database configuration statement in the quota
section, e.g.:
quota {
database /etc/mail/quota.db;
}
User quotas can be kept in an SQL table as well. Currently (as of mailutils version 3.14) it is assumed that this table can be accessed using the credentials set in ‘sql’ configuration statement (see SQL Statement).
For example, suppose you have the following quota table:
create table mailbox_quota ( user_name varchar(32) binary not null, quota int, unique (user_name) );
To retrieve user quota the following query can be used:
SELECT quota FROM mailbox_quota WHERE user_name='${user}'
To define this query use the sql-query statement:
quota {
sql-query "SELECT quota "
"FROM mailbox_quota "
"WHERE user_name='${user}'";
}
There are no special provisions for specifying group quotas, similar to
‘DEFAULT’ in DBM databases. This is because group quotas can
easily be implemented using SQL language. Mda
always uses the first tuple from the set returned by mailbox quota
query. So, you can add a special entry to the mailbox_quota
table that would keep the group quota. In the discussion below we assume
that the user_name column for this entry is lexicographically
less than any other user name in the table. Let’s suppose the group
quota name is ‘00DEFAULT’. Then the following query:
SELECT quota
FROM mailbox_quota
WHERE user_name IN ('${user}','00DEFAULT')
ORDER BY user_name DESC
will return two tuples if the user is found in
mailbox_quota. Due to ORDER statement, the first tuple
will contain quota for the user, which will be used by
mda. On the other hand, if the requested user name is not
present in the table, the above query will return a single tuple
containing the group quota.
The following configuration statement instructs maidag to
use this query for retrieving the user quota:
quota {
sql-query "SELECT quota "
"FROM mailbox_quota "
"WHERE user_name IN ('${user}','00DEFAULT') "
"ORDER BY user_name DESC";
}
mdaMda can use global or per-user mail filters to
decide whether to deliver the message, and where to deliver it. As of
Mailutils version 3.14, such mail filters may be written in
the following languages:
Mail filters to use are specified using ‘script’ configuration statement. The following meta-symbols can be used in its argument:
Expands to the recipient home directory.
Expands to the recipient user name.
By default, the filename extension decides which scripting language will be used. User can alter the choice using ‘language’ configuration statement. For example:
script {
language python;
pattern "~/.maidag-py-filter";
}
The file name of the Sieve filter to use is specified using ‘script’ configuration statement. For example, the following configuration statement:
script {
pattern "~/.maidag.sv";
}
instructs maidag to use file .maidag.sv in the
recipient home directory as a Sieve filter.
Normal message delivery is attempted if execution of the Sieve code
ended with keep action (either implicit or explicit).
Other Sieve actions are executed as described in Actions. For
example, to deliver message to another mailbox, use the
fileinto action.
Any modifications to headers or body of the message performed by the Sieve code will be visible in the delivered message.
The file name of the Scheme mail filter is specified using ‘script’ configuration statement. For example, the following configuration statement:
script {
pattern "~/.maidag.scm";
}
instructs mda to use file .maidag.scm in the
recipient home directory as a Scheme filter.
The file name of the Python mail filter is specified using ‘script’ configuration statement. For example, the following configuration statement:
script {
pattern "~/.maidag.py";
}
instructs mda to use the file .maidag.py in the
recipient home directory as a Python filter.
A simple example of a mail filter written in Python:
from mailutils import *
import maidag
import re
msg = message.Message (maidag.message)
hdr = msg.header
try:
if 'List-Post' in hdr and 'Received' in hdr \
and hdr['Received'].find ('fencepost.gnu.org') != -1:
# check envelope's sender address
m = re.search (r'([\w\-]+)-bounces\+([\w]+)=.*',
msg.envelope.get_sender ())
if m:
lbox = m.group (1)
user = m.group (2)
# open destination mailbox and append message
dst = mailbox.MailboxDefault ('~/Mail/%s' % lbox)
dst.open ('ac')
dst.append_message (msg)
dst.close ()
# set deleted flag so maidag will not deliver msg elsewhere
msg.attribute.set_deleted ()
except Exception:
pass
A forward file is a special file in the user’s home directory that contains the email address of the mailbox where the user wants to forward his mail. Normally, forward files are processed by MTA. However, there are some MTA that lack this feature. One of them is MeTA1.
Mda provides a forwarding feature that is useful to
compensate the lack of it. This feature is controlled by the
forward section in the configuration file:
forward {
# Process forward file.
file name;
# Configure safety checks for the forward file.
file-checks (list);
}
The name of the forward file is given by the file
statement in the forward section. A common usage is:
forward {
file .forward;
}
The forward file is always searched in the recipient home directory.
Before actually using the forward file, a number of safety checks are
performed on it. If the file fails to pass one of these checks, no
forwarding is performed and the message is delivered as usual. These
checks are configured using the forward.file-checks statement:
forward {
file .forward;
file-checks (list);
}
Its argument is a list of the following keywords:
The file must not be group writable.
The file must not be world writable.
The file cannot be a symlink in a writable directory.
The file cannot reside in a group writable directory.
The file cannot reside in a world writable directory.
All of the above checks.
The default is ‘file-checks all’.
Each of these keywords may be prefixed by ‘no’ to disable this particular check. For example:
forward {
file-checks (nodir_iwoth, nodir_iwgrp);
file .forward;
}
The behavior of mda is affected by the following configuration
statements:
| Statement | Reference |
|---|---|
| debug | See debug statement. |
| mailbox | See mailbox statement. |
| locking | See locking statement. |
| pam | See pam statement. |
| sql | See sql statement. |
| virtdomain | See virtdomain statement. |
| radius | See radius statement. |
| ldap | See ldap statement. |
| auth | See auth statement. |
| mailer | See mailer statement. |
If bool is true, log to standard error instead of syslog.
This section contains general delivery settings:
deliver {
domain string;
exit-multiple-delivery-success arg;
};
Default email domain.
In case of multiple delivery, exit with code 0 if at least one delivery succeeded.
Controls the forwarding support:
forward {
file name;
file-checks (list);
}
Defines the name of the forward file. E.g.:
forward {
file .forward;
}
See Forwarding, for a detailed description.
Configures safety checks to be performed on the forward file prior to using it. See Forwarding, for a detailed description.
This section configures mail quota support. See Mailbox Quotas, for a detailed description.
quota {
database name;
sql-query query;
exit-tempfail bool;
}
Sets the name of the quota database in DBM format. See DBM Quotas.
If the quotas are kept in a SQL table, this statement defines the SQL query to retrieve the quota for a given user name. See SQL Quotas.
By default, if a message cannot be delivered because the user has
exceeded its mail quota, or its delivery would cause it to be
exceeded, MDA exits with the ‘service unavailable’
status, which causes MTA to return the 550 code. If
exit-tempfail is set to true, it will return a temporary error
instead.
Controls scripting. See MDA Scripting.
script {
language lang;
pattern glob;
}
Defines the language that is used for scripting. Allowed values for lang are: ‘sieve’, ‘scheme’, or ‘python’. See scripting language.
Defines the pattern for the script file name. The ‘~’ at the begiining of the pattern will be replaced with the name of the home directory of the recipient user. The ‘%u’ in pattern will be replaced with the recipient user name, and ‘%h’ with the home directory for that user.
This subsection explains how to implement mailing lists in
mda using the ‘prog’ mailbox scheme.
Delivery to the ‘prog’ mailbox results in invoking the specified command with the given arguments and passing the message to its standard input. There are two ways to specify a ‘prog’ mailbox:
Here, program is the absolute pathname of the program binary, and args are its arguments, separated by ‘&’ signs.
In this notation, args are command line arguments separated by white space.
In both cases, args do not include argv[0].
The ‘prog’ mailbox can be used to implement mailing lists.
For example, suppose that the mda configuration contains:
auth {
authorization (sql, system);
authentication (generic, system);
}
sql {
interface mysql;
db mail;
getpwnam "SELECT user as name, mailbox, "
"'x' as passwd, 500 as uid, 2 as gid, "
"'/nonexistent' as dir, '/sbin/nologin' as shell "
"FROM userdb "
"WHERE user='${user}'";
}
Then, the following entries in the ‘userdb’ table implement the mailman@yourdomain mailing list:
mysql> select * from userdb; +---------------------+---------------------------------------+ | user | mailbox | +---------------------+---------------------------------------+ | mailman | |/usr/bin/mailman post mailman | | mailman-admin | |/usr/bin/mailman admin mailman | | mailman-bounces | |/usr/bin/mailman bounces mailman | | mailman-confirm | |/usr/bin/mailman confirm mailman | | mailman-join | |/usr/bin/mailman join mailman | | mailman-leave | |/usr/bin/mailman leave mailman | | mailman-owner | |/usr/bin/mailman owner mailman | | mailman-request | |/usr/bin/mailman request mailman | | mailman-subscribe | |/usr/bin/mailman subscribe mailman | | mailman-unsubscribe | |/usr/bin/mailman unsubscribe mailman | +---------------------+---------------------------------------+
The LMTP is a local mail transport protocol defined in RFC
2033. GNU Mailutils is shipped with lmtpd - a daemon for
delivering messages using this protocol.
The daemon shares most of its codebase and configuration with
mda and consequently provides the same features.
See mda, for a detailed description of these.
The behavior of lmtpd is affected by the following configuration
statements:
| Statement | Reference |
|---|---|
| server | See Server Settings |
| acl | See acl statement. |
| tcp-wrappers | See tcp-wrappers statement. |
| debug | See debug statement. |
| mailbox | See mailbox statement. |
| locking | See locking statement. |
| pam | See pam statement. |
| sql | See sql statement. |
| virtdomain | See virtdomain statement. |
| radius | See radius statement. |
| ldap | See ldap statement. |
| auth | See auth statement. |
| mailer | See mailer statement. |
lmtpd with MeTA1.MeTA1 (http://meta1.org) communicates with the delivery agent using LMTP.
The socket to listen for LMTP requests must be specified using the
server statement (see Server Settings). For the purposes of
this section, let’s suppose lmtpd will listen on a
UNIX socket /var/spool/meta1/lmtpsock. Then, the
following (minimal) lmtpd configuration will do the job:
# Run as daemon. mode daemon; # Switch to this group after startup. group meta1c; # Configure server: server unix:///var/spool/meta1/lmtpsock { transcript no; };
To configure MeTA1 to use this socket, add the following statement to the ‘smtpc’ section in /etc/meta1/meta1.conf:
LMTP_socket="lmtpsock";
The putmail utility reads a message from its standard input
and delivers it to the specified mailbox URL. The usage is:
putmail URL
For example, to deliver mail to a local mailbox /var/spool/mail/test:
putmail /var/spool/mail/test
Of course, this would work only it the test mailbox is writable
for the user invoking putmail.
The smtp mailbox scheme can be used for remote delivery. For
example:
putmail 'smtp://mail.example.org;to=ovr'
The program will initiate SMTP dialog with the server ‘mail.example.org’ and will send the message from its standard input to the user ‘ovr’ on that server.
Specify the sender address. If not used, the current user name will be used.
Define scripting language for the next --script option. Valid arguments are ‘sieve’, ‘scheme’ and ‘python’.
Use this header to identify messages when logging Sieve actions
Set the name of the user-defined mail filter. See MDA Scripting, for a detailed discussion of the scripting feature.
The behavior of putmail is affected by the following configuration
statements:
| Statement | Reference |
|---|---|
| debug | See debug statement. |
| mailbox | See mailbox statement. |
| locking | See locking statement. |
| pam | See pam statement. |
| sql | See sql statement. |
| virtdomain | See virtdomain statement. |
| radius | See radius statement. |
| ldap | See ldap statement. |
| auth | See auth statement. |
| mailer | See mailer statement. |
The utility also accepts all MDA configuration statements: See Conf-mda.
For each file given in its command line, mimeview attempts
to autodetect its type and invoke an appropriate file viewer.
To detect the file type, mimeview uses mime.types
file. This file is a part of Common UNIX Printing System,
mime.types in mime.types man page. By default
mimeview searches for mime.types in
$prefix/etc/cups/4, however its exact location can be specified
at runtime as well (see --mimetypes below).
Once file MIME type is successfully determined, mimeview
consults mailcap files in order to determine how to display
the file. It does so essentially in the same manner as
metamail utility, i.e., it scans all files specified
in METAMAIL environment variable until it finds an entry
describing the desired file format or until the list of files is
exhausted. If METAMAIL variable is not set, mimeview
uses the following default path instead:
$HOME/.mailcap:/usr/local/etc/mailcap:\ /usr/etc/mailcap:/etc/mailcap:\ /etc/mail/mailcap:/usr/public/lib/mailcap
The following table summarizes options specific for mimeview:
By default mimeview asks for confirmation before running
interpreter to view a message. If this option is used without
argument, it disables the default behavior for all message
types. Otherwise, if argument type-list is given, it specifies
a comma-separated list of MIME types for which no questions should be
asked. Elements of this list may include shell-style globbing
patterns, e.g. setting
--no-ask='text/*,image/jpeg'
will disable prompting before displaying any textual files, no matter what their subtype is, and before displaying files with type ‘image/jpeg’.
Notice, that when the long form is used, its argument must be separated from the option by a single equal sign, as shown in the example above. When the short form (-a) is used, its argument must follow the option immediately, without any intervening whitespace, e.g. -a'text/*').
Enables debugging output. Flags is a sequence of characters specifying the desired debugging level. Following characters are meaningful in flags:
Enables debugging of mime.types parser
Enables debugging of mime.types lexical analyzer (warning: produces very copious output)
Prints basic information about actions to be executed and reports about exit status of executed commands.
Additionally displays each file name along with its MIME type
Additionally traces the process of looking up the matching entry
in mailcap files.
Additionally, enables debugging of mime.types parser (‘g’).
Additionally, enables debugging of mime.types lexer (‘l’).
The same as 4, currently.
If flags are not given, the default ‘2’ is assumed.
Run metamail to display files, instead of using the internal
mechanisms. If file is specified, it is taken as
metamail command line.
This options tells mimeview that it should run in
non-interactive mode. In this mode prompting is disabled, and
the normal mailcap command field is not executed. Instead
mimeview will execute the command specified in
the print field. If there is nothing in the print field,
the mailcap entry is ignored and the search continues for a matching
mailcap entry that does have a print field.
Notice, that unlike in metamail -h, this option does
not force mimeview to send the output to the printer
daemon.
When used with --metamail option, this option passes
-h flag to the invocation of metamail.
By default mimeview behaves as if given
--no-interactive option whenever its standard input is not
a tty device.
Identifies and prints the MIME type for each input file.
Do not do anything, just print what would be done. Implies --debug=1, unless the debugging level is set up explicitly.
Use file as mime.types file. If file is a directory, use file/mime.types
Check syntax of the mime.types file and exit. Command line arguments are ignored.
The following configuration statements affect the behavior of
mimeview:
| Statement | Reference |
|---|---|
| debug | See Debug Statement. |
Read file instead of the default mime.types.
Use program to display files.
The pop3d daemon implements the Post Office Protocol
Version 3 server.
pop3d has two operation modes:
The server is started from /etc/inetd.conf file:
pop3 stream tcp nowait root /usr/local/sbin/pop3d pop3d
This is the default operation mode.
The server runs as daemon, forking a child for each new connection.
The server operation mode is configured using mode statement
(see mode).
POP3 clients often login frequently to check for new mail. Each new connection implies authenticating the user and opening his maildrop and can be very resource consuming. To reduce server load, it is possible to impose a minimum delay between any two consecutive logins. This is called ‘LOGIN-DELAY’ capability and is described in RFC 2449.
As of version 3.14, GNU Mailutils pop3d allows
to set global login delay, i.e. such enforcement will affect all POP3
users. If a user attempts to log in before the specified login delay
expires, he will get the following error message:
-ERR [LOGIN-DELAY] Attempt to log in within the minimum login delay interval
The message will be issued after a valid password is entered. This prevents this feature from being used by malicious clients for account harvesting.
To enable the login delay capability, specify the minimum delay
using login-delay configuration statement, e.g.:
login-delay 60;
The pop3d utility keeps each user’s last login time in a
special DBM file, called login statistics database, so to be
able to use this feature, Mailutils must be compiled with DBM support.
By default, the login statistics database is called
/var/run/pop3-login.db. You can change its name using
stat-file configuration statement:
login-delay 60; stat-file /tmp/pop.login.db;
The login delay facility will be enabled only if pop3d is
able to access the statistics database for both reading and
writing. If it is not, it will report this using syslog and
start up without login delay restrictions. A common error message
looks like:
Unable to open statistics db: Operation not permitted
You can check whether your pop3d uses login delays by
connecting to it and issuing the ‘CAPA’ command. If login delays
are in use, there response will contain the string ‘LOGIN-DELAY
n’, where n is the actual login delay value.
Automatic expiration of messages allows you to limit the period of
time users are permitted to keep their messages on the server. It is
enabled by expire configuration statement:
expire n;Enable automatic expiration of messages after n days.
The current implementation works as follows. When a message is
downloaded by RETR or TOP command, it is marked with
‘X-Expire-Timestamp: n’ header, where n is current
value of UNIX timestamp. The exact expiration mechanism
depends on you. Mailutils allows you two options:
pop3d upon closing the
mailbox. You specify this mechanism using delete-expired
configuration statement:
delete-expired bool;If bool is ‘true’, delete expired messages after receiving
the QUIT command.
sieve from
GNU Mailutils and the following script:
require "timestamp";
# Replace "5" with the desired expiration period
if timestamp :before "X-Expire-Timestamp" "now - 5 days"
{
discard;
}
This script will remove expired messages 5 days after the
retrieval. Replace ‘5’ with the desired expiration period and
make sure it equals the argument to expire configuration keyword.
The statement expire 0 means the client is not permitted to
leave mail on the server. It always implies delete-expired true.
The bulletin feature allows you to send important announcements to all POP3 users without mailing them. It works by creating a bulletin source mailbox and sending the announcements to it.
After a user successfully authenticates, pop3d checks the
last bulletin number the user receives. The bulletin number
refers to the number of the bulletin message in the bulletin source
mailbox. If the latter contains more messages, these are appended to
the user mailbox.
The user last bulletin number can be kept in two places. First, it
can be stored in file .popbull in his home directory. Secondly,
if Mailutils is compiled with DBM support, the numbers can be kept in
a DBM file, supplied via bulletin-db configuration statement. If
both the database and the .popbull file are present, the data
from the database take precedence.
To enable this feature, use the following configuration statements:
bulletin-source mboxSet the URL of the bulletin source mailbox.
bulletin-db fileSet the name of the database file to keep last bulletin numbers in.
The following example instructs pop3d to look for the
bulletin messages in MH folder /var/spool/bull/mbox
and to keep the database of last delivered bulletin numbers in
/var/spool/bull/numbers.db:
bulletin-source mh:/var/spool/bull/mbox; bulletin-db /var/spool/bull/numbers.db;
The following configuration file statements affect the behavior of
pop3d.
| Statement | Reference |
|---|---|
| debug | See debug statement. |
| tls | See tls statement. |
| tls-file-checks | See tls-file-checks statement. |
| mailbox | See mailbox statement. |
| locking | See locking statement. |
| logging | See logging statement. |
| pam | See pam statement. |
| sql | See sql statement. |
| virtdomain | See virtdomain statement. |
| radius | See radius statement. |
| ldap | See ldap statement. |
| auth | See auth statement. |
| server | See Server Settings. |
| acl | See acl statement. |
| tcp-wrappers | See tcp-wrappers statement. |
Configure the use of TLS encryption for inetd mode.
In daemon mode, this statement sets the type of TLS encryption to
use in all server blocks that lack the tls-mode statement
(see Server Statement).
Allowed values for mode are:
TLS is not used. The STLS command won’t be available even if
the TLS configuration is otherwise complete.
TLS is initiated when the user issues the appropriate command. This is the default when TLS is configured.
Same as above, but the use of TLS is mandatory. The authentication state is entered only after TLS negotiation has succeeded.
TLS is always forced when the connection is established (POP3S protocol).
On startup, clear deletion marks from all the messages.
Automatically expire read messages after n days. See Auto-expire, for a detailed description.
Delete expired messages upon closing the mailbox. See Auto-expire, for a detailed description.
Set the minimal allowed delay between two successive logins. See Login delay, for more information.
Set the name of login statistics file for the login-delay
facility. See Login delay, for more information.
Get bulletins from the specified mailbox. See Bulletins, for a detailed description.
Set bulletin database file name. See Bulletins, for a detailed description.
The following table summarizes all pop3d command line options.
Run in standalone mode. An optional number specifies the maximum number of child processes allowed to run simultaneously. When it is omitted, it defaults to 10 processes. Please note, that there should be no whitespace between the -d and its parameter.
Run in inetd mode.
Remain in foreground.
The Mailutils common options are also understood. See Common Options.
GNU imap4d is a daemon implementing IMAP4 rev1 protocol
for accessing and handling electronic mail messages on a server. It can
be run either as a standalone program or from inetd.conf file.
GNU imap4d supports a notion of namespaces defined
in RFC 2342. A namespace can be regarded as a list of entities,
defining locations to which the user has certain access rights. Each
entity includes the prefix, under which the mailboxes can be
found, hierarchy delimiter, a character used to delimit parts of
a path to a mailbox, and a directory on the file system on the
server, which actually holds the mailboxes. Among these three values,
only first two are visible to the client using the IMAP
‘NAMESPACE’ command.
There are three namespaces:
A namespace that is within the personal scope of the authenticated user on a particular connection. The user has all permissions on this namespace.
By default, this namespace contains a single prefix:
prefix: "" delimiter: / directory: home directory of the user
A namespace that consists of mailboxes from the “Personal Namespaces”
of other users. The user can read and list mailboxes from this
namespace. However, he is not allowed to use ‘%’ and ‘*’
wildcards with LIST command, that is he can access a
mailbox only if he knows exactly its location.
By default, this namespace is empty.
A namespace that consists of mailboxes that are intended to be shared amongst users and do not exist within a user’s Personal Namespace. The user has all permissions on this namespace.
By default, this namespace is empty.
The default values ensure that each user is able to see or otherwise access mailboxes residing in the directories other than his own home.
These defaults can be changed using the namespace block
statement:
namespace name {
mailbox-mode mode;
prefix pfx {
directory path;
delimiter chr;
mailbox-type type;
}
}
The name argument to the namespace statement declares
which namespace is being configured. Allowed values are:
‘personal’, ‘other’, and ‘shared’.
The mailbox-mode statement configures the file mode for the
mailboxes created within that namespace (provided that the directory
permissions allow the user to create mailboxes). The mode
argument is a comma-delimited list of symbolic mode settings, similar
to that used by chmod. Each setting begins with a
letter ‘g’, which means set mode bits for file group, or
‘o’, which means set mode bits for other users (note, that there
is no ‘u’ specifier, since user ownership of his mailbox cannot
be changed). This letter is followed by an ‘=’ (or ‘+’), and
a list of modes to be set. This list can contain only two letters:
‘r’ to set read permission, and ‘w’ to set write permission.
For example, the following statement sets read and write permissions for the group:
mailbox-mode g=rw;
The prefix statement configures available prefixes and
determines their mappings to the server’s file system. The pfx
argument defines the prefix which will be visible to the IMAP client.
The directory statement defines the directory in the file
system to which pfx is mapped. Exactly one directory
statement must be present in each prefix block. The
inerpretation of its argument depends on the namespace in which it
occurs.
When used in the ‘namespace shared’ block, the argument to this statement is interpreted verbatim, as an absolute pathname.
When used in ‘namespace personal’ the argument to
directory statement can contain references to the following
variables (see Variables):
Login name of the user.
Home directory of the user.
For example, the following statement maps the default personal namespace to the directory ‘imap’ in the user’s home directory:
namespace personal {
prefix "";
directory "$home/imap";
}
If the ‘directory’ statement is used within the ‘namespace other’ block, its value can contain the ‘$user’ and ‘$home’ variables as well, but their meaning is different. For the ‘other’ namespace, the ‘$user’ variable is expanded to the part of the actual reference contained between the prefix and first hierarchy delimiter (or the end of the reference, if no delimiter occurs to the right of the prefix). Correspondingly, ‘$home’ expands to the home directory of that user. Consider, for example, the following statement:
namespace other {
prefix "~";
directory "/var/imap/$user";
}
If the client issues the following statement:
1 LIST "~smith" "%"
then ‘$user’ will expand to the string ‘smith’ and the server will look for all mailboxes in the directory /var/imap/smith.
The delimiter statement defines the folder hierarchy delimiter
for that prefix. It is optional, the default value being ‘"/"’.
The mailbox-type statement declares the type of the mailboxes
within that prefix. If present, its argument must be a valid mailbox
type (e.g. ‘mailbox’, ‘maildir’, or ‘mh’). The IMAP
LIST command will display only mailboxes of that type. The
CREATE command will create mailboxes of that type.
In the absence of the mailbox-type statement, the IMAP
LIST command will display mailboxes of any type supported by
Mailutils. The type of newly-created mailboxes is then determined by
the mailbox-type statement (see mailbox-type).
Any number of prefix blocks can be present.
Consider, for example, the following configuration:
namespace personal {
prefix "" {
directory "$home/mailfolder";
}
prefix "#MH:" {
directory "$home/Mail";
delimiter "/";
mailbox-type "mh";
}
}
It defines the personal namespace containing two prefixes. The empty prefix is mapped to the directory mailfolder in the home directory of the currently authenticated user. Any type of mailboxes is supported within that prefix.
The prefix ‘#MH:’ is mapped to the directory Mail in the home directory of the user, and is limited to contain only mailboxes in MH format.
Note that if the prefixes ‘""’ is not defined in the personal namespace, the following default will be automatically created:
prefix "" {
directory "$home";
}
imap4d.The behavior of imap4d is altered by the following
configuration statements:
| Statement | Reference |
|---|---|
| debug | See debug statement. |
| tls | See tls statement. |
| tls-file-checks | See tls-file-checks statement. |
| mailbox | See mailbox statement. |
| locking | See locking statement. |
| logging | See logging statement. |
| pam | See pam statement. |
| sql | See sql statement. |
| virtdomain | See virtdomain statement. |
| radius | See radius statement. |
| ldap | See ldap statement. |
| auth | See auth statement. |
| server | See Server Settings. |
| acl | See acl statement. |
| tcp-wrappers | See tcp-wrappers statement. |
Configures namespace. The argument is one of: ‘personal’,
‘other’, ‘shared’. The following statements (described
below) are allowed within curly braces: mailbox-mode and
prefix.
See Namespace.
Configures the file mode for the mailboxes created within that namespace. The syntax for mode is:
g(+|=)[wr]+,o(+|=)[wr]+
See mailbox-mode.
Configures a prefix and determines its mapping to the server’s file
system. The pfx argument is the prefix which will be
visible to the IMAP client. Available sub-statements are:
directory, delimiter, and mailbox-type.
See prefix.
Defines the directory in the file system to which the prefix is mapped.
See directory.
Defines the folder hierarchy delimiter for the prefix. Argument must be a single character.
See delimiter.
Defines the type of the mailboxes inside that prefix.
See mailbox-type.
Disable LOGIN command, if bool is ‘true’.
Create nonexistent user home directories. See also home-dir-mode, below.
Set file mode for created user home directories. Mode is specified in octal.
The default value for mode is ‘700’ (‘drwx------’ in
ls terms).
Configure PREAUTH mode. Valid arguments are:
Imap4d invokes an external program to authenticate the
connection. The command line is obtained from the supplied string,
by expanding the following meta-variables:
${client_address}Remote IP address in dotted-quad notation;
${client_port}Remote port number;
${server_address}Local IP address;
${server_port}Local port number.
If the connection is authenticated, the program should print the user name, followed by a newline character, on its standard output and exit with code ‘0’.
Otherwise, it should exit with a non-zero exit code.
The remote machine is asked about the requester identity using the identification protocol (RFC 1413). Both plaintext and DES encrypted replies are understood. Optional port specifies the port to use, if it differs from the default ‘113’. It can be either a decimal port number or a symbolic name of a service, listed in /etc/services.
PREAUTH mode is enabled automatically if imap4d is started from command line in interactive mode (-i command line option). The current login name is used as the user name.
If bool is ‘true’, use only preauth mode. If unable to setup it, disconnect immediately.
Set DES keyfile for decoding encrypted ident responses. Used with ‘ident://’ preauth mode.
Use only encrypted IDENT responses.
Set list of fields to return in response to ID command.
Valid field names are:
Package name (‘GNU Mailutils’).
Package version (‘3.14’).
Vendor name (‘GNU’).
The string ‘http://www.gnu.org/software/mailutils’
The string ‘51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA’.
OS name.
OS version number.
Name of the imap4d binary.
Invocation command line.
List of environment variables with their values.
imap4dimap4d may run either in standalone or in inetd
operation modes. When run in “standalone” mode, the server disconnects
from the terminal and runs as a daemon, forking a child for each new
connection.
The “inetd” mode allows to start the server from /etc/inetd.conf file. This is the default operation mode.
imap4 stream tcp nowait root /usr/local/sbin/imap4d imap4d
Run in standalone mode. An optional number specifies the maximum number of child processes the daemon is allowed to fork. When it is omitted, it defaults to 20 processes. Please note, that there should be no whitespace between the -d and its parameter.
Run in inetd mode.
Run in foreground.
Start in preauth mode
Run in test mode.
See also Common Options.
Comsatd is the server which receives reports of incoming mail and notifies users about it. By default, it prints subject, sender name and email, followed by first five lines of each newly arrived message to the tty of the recipient user. Users can customize this behavior.
comsatdRun as a standalone daemon.
The server is started from /etc/inetd.conf file:
comsat dgram udp wait root /usr/sbin/comsatd \ comsatd -c /etc/comsat.conf
This is the default operation mode.
Test mode. In this mode, comsatd takes two arguments:
URL of a mailbox and QID of the message from that
mailbox and prints the notification to the current user tty
(/dev/tty), or file, if it is supplied. If the
~/.biffrc file exists, it will be used. For example:
$ comsatd --test /var/mail/root 34589
Notice, that file is an optional argument. When supplied, it should follow the short option form immediately, or the long option form after the equals sign, e.g.:
$ comsatd --test=logfile /var/mail/root 34589
or
$ comsatd -tlogfile /var/mail/root 34589
Don’t detach from the controlling terminal, remain in foreground.
See also Common Options.
comsatdFollowing configuration statements affect the behavior of
comsatd:
| Statement | Reference |
|---|---|
| debug | See debug statement. |
| logging | See logging statement. |
| mailbox | See mailbox statement. |
| locking | See locking statement. |
| acl | See acl statement. |
These statements control the general behavior of the comsat daemon:
Set maximum number of message body lines to be output.
Enable or disable processing of user’s .biffrc file. By default, it is enabled.
These statements control the way comsatd fights possible
flooding attacks.
Set maximum number of incoming requests per ‘request-control-interval’.
Set the request control interval.
Set initial amount of time to sleep, after the first overflow occurs.
Set overflow control interval. If two consecutive overflows happen within that interval, the overflow-delay-time is doubled.
By default, when a notification arrives, comsatd prints subject,
from headers and the first five lines from the new message to the user’s
tty. The user is allowed to change this behavior by using his own
configuration file. This file should be located in the user’s home
directory and should be named .biffrc. It must be owned by the
user and have its permissions bits set to 0600. (Please note,
that the use of per-user configuration files may be disabled, by
specifying ‘allow-biffrc no’ in the main configuration file, see
see Configuring comsatd).
The .biffrc file consists of a series of statements. Each statement occupies one line and defines an action to be taken upon arrival of a new mail. Very long lines may be split using ‘\’ as the last character on the line. As usual, comments may be introduced with ‘#’ character.
The actions specified in .biffrc file are executed in turn. The following actions are defined:
Produce an audible signal.
Output the arguments to the user’s terminal device. If several arguments are given they will be output separated by single spaces. The newline character will be printed at the end of the output, unless the -n option is used.
Execute program prog with arguments from arglist. prog must be specified with absolute pathname. It may not be a setuid or setgid program.
In the description above, string denotes any sequence of characters. This sequence must be enclosed in a pair of double-quotes, if it contains whitespace characters. The ‘\’ character inside a string starts a C escape sequence. Following meta-characters may be used in strings:
Expands to username
Expands to hostname
Expands to value of message header ‘name’.
Expands to message body. c and l give maximum number of characters and lines in the expansion. When omitted, they default to 400, 5.
Dump to the user’s terminal the contents of ‘From’ and ‘Subject’ headers followed by at most 5 lines of message body.
echo "Mail to \a$u@$h\a\n---\n\
From: $H{from}\n\
Subject: $H{Subject}\n\
---\n\
$B(,5)\
---\n"
The above example can also be written as:
echo Mail to \a$u@$h\a
echo ---
echo From: $H{From}
echo Subject: $H{Subject}
echo ---
echo $B(,5)
echo ---
Produce a bell, then pop up the xmessage window on display :0.0 with the text formatted in the same manner as in the previous example.
beep
exec /usr/X11R6/bin/xmessage \
-display :0.0 -timeout 10 "Mail to $u@$h \n---\n\
From: $H{from}\n\
Subject: $H{Subject}\n\
---\n\
$B(,5)\
---\n"
The primary aim of this implementation is to provide an interface between Mailutils and Emacs using mh-e module.
To use Mailutils MH with Emacs, add the following line to your site-start.el or .emacs file:
(load "mailutils-mh")
For the information about the current state of Mailutils MH implementation please refer to file mh/TODO in the Mailutils distribution directory.
Message sequence numbers are used as UIDs and thus increase monotonically. This means, in particular, that if your inbox has messages in the range ‘X--Y’ and you delete all messages and then incorporate new mail, the first incorporated message will be assigned sequence number ‘Y + 1’ (other MH implementations will assign ‘1’). If this behavior bugs you, add the following setting to your .mh_profile:
Volatile-uidnext: true
You can always renumber your messages starting from ‘1’ by running
folder -pack=1
These options are recognized only if no other arguments are present in the command line. Abbreviations are not recognized. This makes Mailutils MH implementation compatible with the standard usage for GNU tools.
Decodes the input string str as per RFC 2047. Useful in printing ‘From:’, ‘To:’ and ‘Subject:’ headers.
Notice that, unlike the similar NMH function, decode checks the value
of the global profile variable Charset (see Charset variable)
to determine the charset to output the result in. If this variable is
not set, decode returns its argument without any change. If
this variable is set to auto, decode tries to determine
the charset name from the setting of LC_ALL environment
variable. Otherwise, the value of Charset is taken to be the
name of the character set.
Returns package name (string ‘mailutils’).
Returns full package string (e.g. ‘GNU Mailutils 2.1’)
Returns mailutils version.
The function removes any leading whitespace and eventual ‘Re:’ prefix from its argument. Useful for creating subjects in reply messages:
%<{subject}Subject: Re: %(unre{subject})\\n%>
Sets the regular expression used to recognize reply messages. The argument r should be a POSIX extended regular expression. Matching is case insensitive.
For example, the following invocation
%(reply_regex ^\(re|aw|ang|odp\)\(\\[[0-9]+\\]\)?:[[:blank:]])
corresponds to English ‘Re’, Polish ‘Odp’, Norwegian ‘Aw’ or German ‘Ang’, optionally followed by a number in brackets, followed by colon and any amount of whitespace. Notice proper quoting of the regex metacharacters.
See also Reply-Regex (see Reply-Regex variable) and
isreply (see isreply MH function) below.
If str is not given, the value of ‘Subject:’ header is taken.
The function returns true if its argument matches the “reply subject”
regular expression. This expression is set via the global profile variable
Reply-Regex (see Reply-Regex variable) or via the format
function reply_regex.
This function is useful for creating ‘Subject:’ headers in reply messages. For example, consider the following construction:
%<{subject}%(lit)%<(isreply)%?\
(profile reply-prefix)%(concat)%|%(concat Re:)%>\
%(concat{subject})%(printhdr Subject: )\n%>
If the ‘Subject:’ header already contained reply prefix, this construct
leaves it unchanged. Otherwise it prepends to it the value of
Reply-Prefix profile variable, or, if it is unset, the string
‘Re:’.
This expression is used in default replcomps and replgroupcomps files.
This function returns true if the given element is present in the
recipient mask (as modified by -cc or -nocc options) and
false otherwise. It is used in default formats for repl and
comp, e.g.:
%(lit)%<(rcpt to)%(formataddr{to})%>
Notice that this means that usual replcomps file will be ignoring -cc and -nocc options, unless it has been modified as shown above.
Appends whitespace + arg to string register.
Prints the value of string register, prefixed by str. The output is formatted as a RFC 822 header, i.e. it is split at whitespace characters nearest to the width boundary and each subsequent segment is prefixed with horizontal tabulation.
Generates the value for ‘In-reply-to:’ header according to RFC 2822.
Generates the value for ‘References:’ header according to RFC 2822.
Controls the character set in which the components decoded via
the decode (see decode function) format function should be
output.
Keeps the regular expression used to recognize reply messages. The argument should be a POSIX extended regular expression. Matching is case insensitive.
For more information, please see See reply_regex function.
annoThe prompt in interactive mode is ‘Component name:’, instead
of ‘Enter component name:’ displayed by the RAND anno.
If a -component field is not specified and standard input
is not connected to a terminal, anno does not display
the prompt before reading the component from the standard input.
RAND anno displays the prompt anyway.
burstThe utility is able to burst both RFC 934 digest messages and MIME multipart messages. It provides two additional command line options: -recurse and -length.
The -recurse option instructs the utility to recursively expand the digest.
The -length option can be used to set the minimal encapsulation
boundary length for RFC 934 digests. Default length is 1,
i.e. encountering one dash immediately following a newline triggers
digest decoding. It is OK for messages that follow RFC 934
specification. However, many user agents do not precisely follow it,
in particular, they often do not escape lines starting with a dash by
‘- ’ sequence. Mailman is one of such agents. To cope
with such digests you can set encapsulation boundary length to a higher
value. For example, bounce -length 8 has been found to be
sufficient for most Mailman-generated digests.
compUnderstands -build option.
fmtdumpThis command is not provided. Use fmtcheck instead.
incinc to move
messages into another folder after incorporating them. This option
has effect only if the -truncate option has also been
specified and the underlying mailbox supports the ‘move’
operation. Currently only ‘imap’ and ‘imaps’ mailboxes
support it. For example, the following command moves incorporated
messages into the ‘archive’ folder:
inc -file imaps://imap.gmail.com -moveto=archive
The ‘moveto’ URL parameter can be used instead of this option, e.g.:
inc -file 'imaps://imap.gmail.com;moveto=archive'
inc is able to incorporate messages from several
source mailboxes. These are specified via multiple -file
options, e.g.:
inc -truncate \
-file 'imaps://imap.gmail.com;moveto=archived' \
-file pops://mail.gnu.org \
-file /var/mail/root
Moves incorporated messages into another folder. This was discussed above.
Disables the previous -moveto option.
Controls source mailbox truncation. If bool is not given or it is ‘yes’, the mailbox will be truncated after successful processing. If bool is ‘no’, the source mailbox will not be truncated.
mhlThe ‘ignores’ keyword can be used in variable list. In that case, if its value contains more than one component name it must be enclosed in double-quotes, e.g.:
leftadjust,compwidth=9,"ignores=msgid,message-id,received"
The above is equivalent to the following traditional notation:
leftadjust,compwidth=9 ignores=msgid,message-id,received
The ‘MessageName’ component is not yet implemented.
Interactive prompting is not yet implemented.
The following format variables are silently ignored: ‘center’, ‘split’, ‘datefield’.
mhnmhn editing mode. This
is also the default mode. This differs from the standard
mhn, which switches to the editing mode only if no other
options were given and the input file name coincides with the value of
mhdraft environment variable.
mhn
prints the decoded message content using moreproc
variable. Standard mhn in this case used to print ‘don't
know how to display content’ diagnostic.
The default behaviour is to pipe the content to the standard input
of the mhn-show-type[/subtype] command. This is altered to using a
temporary file if the command contains %f or %F escapes.
Content-Disposition header contains ‘filename=’,
and mhn is invoked with -auto switch, it
transforms the file name into the absolute notation and uses it only
if it lies below the current mhn-storage directory. Standard
mhn only requires that the file name do not begin with ‘/’.
Before saving a message part, GNU mhn checks if the file already
exists. If so, it asks whether the user wishes to rewrite it. This
behaviour is disabled when -quiet option was given.
mhparamThe -all mode does not display commented out entries.
pickNew command line option -cflags allows to control the type of regular expressions used. The option must occur right before --component pattern or equivalent construct (like -cc, -from, etc.)
The argument to this option is a string of type specifications:
| B | Use basic regular expressions |
| E | Use extended regular expressions |
| I | Ignore case |
| C | Case sensitive |
Default is ‘EI’.
The flags remain in effect until the next occurrence of -cflags option.
Sample usage:
pick -cflag BC -subject '*a string'
The date comparison options (-before and -after accept date specifications in a wide variety of formats, e.g.:
pick -after 20030301 pick -after 2003-03-01 pick -after 01-mar-2003 pick -after 2003-mar-01 pick -before '1 year ago' etc...
prompterIf prompter is built without readline, it accepts
the following character notations:
Here, n stands for a single octal digit.
This notation is translated to the ASCII code ‘chr + 0100’.
prompter
will add it automatically.
refilerefile never makes links even if called with
-link option. The latter is actually a synonym for -copy,
which preserves the original message.
replUnderstands -use option. Disposition shell provides
use command.
rmmMailutils rmm does not delete any messages. Standard
rmm in this case deletes all messages preceding the
non-existent one.
rmm utility will unlink messages, if the rmmproc
profile component has empty value, e.g.:
rmmproc:
sortmNew option -numfield specifies numeric comparison for the given field.
Any number of -datefield, -textfield and -numfield options may be given, thus allowing to build sort criteria of arbitrary complexity.
The order of -.*field options sets the ordering priority. This
differs from the behaviour of the standard sortm, which
always orders datefield-major, textfield-minor.
Apart from sorting the mailfolder the following actions may be specified:
List the ordered messages using a format string given by -form or -format option.
Do not actually sort messages, rather print what would have been done. This is useful for debugging purposes.
The mailutils utility is a multi-purpose tool shipped with
Mailutils. It can be used for various mail and database-related
tasks, as well as an auxiliary tool for compiling and linking programs
with Mailutils.
Mailutils is a command line tool. Its invocation syntax is:
mailutils [options] command [args]
where options are options that affect the behavior of
mailutils as a whole, command instructs it what it is to do
and args are any arguments the command needs in order to be
executed.
The commands are:
Decodes or encodes email message headers.
Tests Mailutils access control lists.
Shows compiler options needed to compile with Mailutils.
Invokes a DBM management tool.
Applies a chain of filters to the input.
Displays a terse help summary.
Invokes an IMAP4 client shell (in development).
Displays information about Mailutils compile-time configuration.
Constructs a ld(1) command line for linking a program with Mailutils.
Logs information using Mailutils log facility.
Invokes a POP3 client shell.
Queries configuration values.
Scans wicket for matching URLs
The mailutils help command lists all available options and command
names along with short descriptions of what each of them does. It is
similar to the mailutils --help option.
A command name can be supplied as an argument to
help, in which case it will display a help page for that
particular command, e.g.:
mailutils help ldflags
will output help for the ldflags command. It is synonymous
to the --help option used with that particular command, e.g.:
mailutils ldflags --help.
The mailutils info command displays information about Mailutils
compile-time configuration. In normal form its output lists a single
configuration flag per line, e.g.:
$ mailutils info VERSION=2.99.93 SYSCONFDIR=/etc MAILSPOOLDIR=/var/mail/ SCHEME=mbox LOG_FACILITY=mail IPV6 USE_LIBPAM HAVE_LIBLTDL WITH_GDBM WITH_GNUTLS WITH_GSASL
A configuration flag can consist either of a single word, indicating that a particular capability has been enabled at compile time, or of a keyword/value pair delimited by an equal sign, which indicates a particular value used by default for that feature. For example, ‘IPV6’ means that Mailutils was compiled with support for IPv6, whereas ‘SYSCONFDIR=/etc’ means that the default place for configuration files is in /etc directory.
Such short output is convenient for using mailutils info in scripts
to decide whether it is possible to use a given feature. To assist
human users, the --verbose (-v) option is provided.
It prints a short description next to each flag:
$ mailutils info --verbose VERSION=2.99.93 - Version of this package SYSCONFDIR=/etc - System configuration directory MAILSPOOLDIR=/var/mail/ - Default mail spool directory SCHEME=mbox - Default mailbox type LOG_FACILITY=mail - Default syslog facility IPV6 - IPv6 support USE_LIBPAM - PAM support HAVE_LIBLTDL - a portable `dlopen' wrapper library WITH_GDBM - GNU DBM WITH_GNUTLS - TLS support using GNU TLS WITH_GSASL - SASL support using GNU SASL
The mailutils cflags command shows compiler options needed to
compile a C source with Mailutils. It is intended for use in
configuration scripts and Makefiles, e.g.:
CFLAGS=-g -O2 `mailutils cflags`
The mailutils ldflags command is a counterpart of cflags
which is used for linking. It constructs a ld command line
for linking a program with Mailutils.
When used without arguments, it outputs ld arguments which
would link only with the core Mailutils library libmailutils, e.g.:
$ mailutils ldflags -L/usr/local/lib -lmailutils
This command accepts a number of keywords which allow to select a particular subset of Mailutils libraries to link with. In particular, the argument ‘all’ instructs it to link in all available libraries:
$ mailutils ldflags all -L/usr/local/lib -lmu_mbox -lmu_mh -lmu_maildir -lmu_imap -lmu_pop \ -lmu_mailer -lmu_compat -lmailutils -lmu_auth -lgsasl -lgnutls -lgcrypt \ -lldap -lgnuradius -lpam -ldl
Other available keywords are:
Link in the UNIX mbox format support.
Link in the MH format support.
Link in the Maildir format support.
Link in the IMAP protocol support.
Link in the POP protocol support.
Enable support for mailers.
Link in the support for Sieve mail filtering language.
Link in the support for DBM databases (libmu_dbm library).
Link in the Mailutils authentication library.
Provide Guile language bindings.
Provide Python language bindings.
The command mailutils stat shows status of a mailbox. The
name or URL of the mailbox to operate upon is supplied in the first
argument. If not given, the command will display status of the
invoking user system mailbox.
$ mailutils stat type: maildir path: /var/mail/smith URL: /var/mail/smith size: 3498 messages: 24 recent messages: 3 first unseen: 20 uidvalidity: 1338543026 next uid: 87 access: 2016-12-15 09:15:08 +0200
The output format is controlled by the --format (-c) option. Its argument is the desired format string, composed of ordinary characters, which are reporduced on standard output verbatim, backslash sequences, and format specifiers, beginning with ‘%’.
Backslash sequences are interpreted as in C.
A format specifier consists of a leading ‘%’ followed by a letter. Optional ‘:’ may occur between ‘%’ and the letter. Its presense instructs the program to print the description of the corresponding value before the value itself.
The following format sequences are understood:
Name of the mailbox as supplied in the command line. If
mailutils stat was used without explicit mailbox argument,
‘%f’ is equivalent to ‘%U’.
Type of the mailbox (‘mbox’, ‘maildir’, etc.). The description string is ‘type’.
Path to the mailbox. In case of remote mailboxes, it is the path part of the mailbox URL. Description string: ‘path’.
URL of the mailbox. Description string: ‘URL’.
Size of the mailbox in octets. Description string: ‘size’.
Number of messages in the mailbox. Description string: ‘messages’.
Number of recent (unread) messages in the mailbox. Description string: ‘recent messages’.
Index of the first unseen message. Description string: ‘first unseen’.
The UIDVALIDITY value. Description string: ‘uidvalidity’.
The UID value which will be assigned to the new message to be incorporated into the mailbox. Description string: ‘next uid’.
Access time of the mailbox, as a number of seconds since the epoch.
Access time of the mailbox in human-readable format.
The mailutils query command queries values from Mailutils
configuration files. It takes one or more configuration paths
(see Paths) as its arguments. On output, it displays the values
it found, each value on a separate line. If the requested value is a
block statement it is displayed in full. For example, if main
configuration file contained:
logging {
syslog yes;
facility mail;
}
Then:
$ mailutils query .logging.syslog
syslog yes;
$ mailutils query .logging.syslog .logging.facility
syslog yes;
facility mail;
$ mailutils query .logging
logging {
syslog yes;
facility mail;
};
Several command line options allow to modify output format. The --value option instructs the command to output only values:
$ mailutils query --value .logging.syslog yes
The --path option instructs it to print full pathnames for each value:
$ mailutils query --path .logging.syslog logging.syslog: yes
The --program option instructs mailutils to behave as if
it was called under another program name. For example, the following
command:
$ mailutils query --program=pop3d .server.transcript
will return the value of the ‘.server.transcript’ statement which
the pop3d utility would see.
By default, mailutils query operates on the main configuration
file. Another configuration file can be supplied using the
--file (-f) option:
$ mailutils query --file /usr/local/etc/file.conf .pidfile
The mailutils 2047 command is a filter for decoding or encoding
email message headers formatted in accordance with RFC 2047 (see
http://www.faqs.org/rfcs/rfc2047.html. By default, it operates
in encode mode and assumes the ‘iso-8859-1’ encoding. If
arguments are supplied in the command line, they are treated as the
text to operate upon. Otherwise the command acts as a UNIX filter,
reading lines from the standard input and printing results on the
standard output.
For example:
$ mailutils 2047 'Keld Jørn Simonsen <keld@dkuug.dk>' =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>
The decode mode can be requested via the --decode (-d) option:
$ mailutils 2047 --decode '=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= \ <keld@dkuug.dk>' Keld Jørn Simonsen <keld@dkuug.dk>
The --charset (-c) option changes the default character set. It is meaningful both in decode and in encode modes. In decode mode it instructs the utility to convert the output to the given character set. In encode mode it indicates the encoding of the input data, which will be reflected in the resulting string:
$ mailutils 2047 --charset=utf-8 'Keld Jørn Simonsen <keld@dkuug.dk>' =?utf-8?Q?Keld J=C3=B8rn Simonsen <keld@dkuug.dk>?=
The --encoding (-E) option can be used in encode mode to change the output encoding. Valid arguments for this option are: ‘quoted-printable’ (the default) or ‘base64’.
The --newline (-n) option prints an additional newline character after each line of output.
The mailutils filter command applies a chain of filters to the
input. The filters to apply and their arguments are given
in the command line. The full invocation syntax is:
mailutils filter [option] filter-chain
The syntax for filter-chain in Backus-Naur form follows:
<filter-chain> ::= <filter> | <filter-chain> "+" <filter> <filter> ::= <filter-spec> <ARG>* <filter-spec> ::= <WORD> | "~" <WORD>
where <WORD> stands for the filter name and <ARG> represents filter arguments. To obtain a list of known filter names, run:
mailutils filter --list
Filters are applied in the order of their appearance, from left to right and operate in encode mode. The plus sign has the same meaning as pipe in shell. The default mode can be changed using the --decode (-d) and --encode (-e) options. Whatever the default mode is, a ‘~’ character before filter name reverts the mode for that filter alone.
For example, to encode the contents of file file.txt in Base64 run:
mailutils filter base64 < file.txt
To convert it to base64 and use CRLF as line delimiters, run:
mailutils filter base64 + crlf < file.txt
The following command will decode the produced output:
mailutils filter --decode crlf + base64
It can also be written as
mailutils filter ~crlf + ~base64
The following example converts the input from ISO-8859-2 to UTF-8, quotes eventual ‘From’ occurring at the beginning of a line, encodes the result in Base64 and changes line delimiters to CRLF:
mailutils filter iconv iso-8859-2 utf-8 + from + base64 + crlf
This final example removes UNIX-style comments from the input and joins continuation lines:
mailutils filter --decode inline-comment -S '#' + linecon
Such invocation can be useful in shell scripts to facilitate configuration file processing.
The mailutils acl command tests Mailutils Access Control Lists. By
default it reads ACL from the Mailutils configuration file section
‘acl’. The command takes a list of IP addresses as its
arguments, applies the ACL to each of them in turn and prints the result.
To select the ACL to test, two options are provided. The --file (-f) option supplies the name of configuration file to read instead of the default one. The --path (-p option supplies the pathname (see Paths) of the ACL section to use instead of the default ‘.acl’. For example, to test ACL in section ‘server 213.130.1.232’ of file /etc/pop3d.conf use:
mailutils acl --file=/etc/pop3d.conf \
--path=/server="213.130.1.232"/acl address
As an example of its use, consider file test.conf with the following contents:
acl {
deny from 10.10.10.1;
deny from 10.10.1.0/24;
log from any "Connect from ${address}";
allow from 10.0.0.0/8;
allow from 192.168.1.0/24;
deny from any;
}
Then, running mailutils acl --file=test.conf 127.0.0.1 you will get:
Testing 127.0.0.1: mailutils: Connect from 127.0.0.1 127.0.0.1: deny
More examples:
$ mailutils acl --file=test.conf 127.0.0.1 10.10.10.1 \
10.10.1.3 10.5.3.1 192.168.1.0 192.168.2.0
Testing 127.0.0.1:
mailutils: Connect from 127.0.0.1
127.0.0.1: deny
Testing 10.10.10.1:
10.10.10.1: deny
Testing 10.10.1.3:
10.10.1.3: deny
Testing 10.5.3.1:
mailutils: Connect from 10.5.3.1
10.5.3.1: accept
Testing 192.168.1.0:
mailutils: Connect from 192.168.1.0
192.168.1.0: accept
Testing 192.168.2.0:
mailutils: Connect from 192.168.2.0
192.168.2.0: accept
The mailutils option --debug-level will give you a deeper
insight into the address matching algorithm:
$ mailutils --debug-level=acl.trace9 acl --file test.conf 127.0.0.1
Testing 127.0.0.1:
mailutils: Checking sockaddr 127.0.0.1
mailutils: 1:deny: Does 10.10.10.1/255.255.255.255 match 127.0.0.1? no;
mailutils: 2:deny: Does 10.10.1.0/255.255.255.0 match 127.0.0.1? no;
mailutils: 3:log: Does any match 127.0.0.1? yes;
mailutils: Expanding "Connect from ${address}";
mailutils: Expansion: "Connect from 127.0.0.1";.
mailutils: Connect from 127.0.0.1
mailutils: 4:accept: Does 10.0.0.0/255.0.0.0 match 127.0.0.1? no;
mailutils: 5:accept: Does 192.168.0.0/255.255.0.0 match 127.0.0.1? no;
mailutils: 6:deny: Does any match 127.0.0.1? yes;
127.0.0.1: deny
See acl.
The mailutils wicket command looks up matching URLs in the
Mailutils ticket file (by default, ~/.mu-tickets) and prints
them. The URLs to look for are supplied in the command line.
Consider the following ticket file as an example:
smtp://foo:bar@* smtp://bar:baz@gnu.org *://baz:qux@* *://quux:bar@gnu.org
Now, running mailutils wicket smtp://bar@gnu.org will show:
smtp://bar@gnu.org: /home/user/.mailutils-tickets:2
(where user is your login name). This means that this URL
matches the line 2 in your .mailutils-tickets file. The
wicket command does not show the actual matching line to
avoid revealing eventual security-sensitive information. You can
instruct it to do so using the --verbose (-v)
option:
$ mailutils wicket -v smtp://bar@gnu.org smtp://bar@gnu.org: /home/user/.mu-tickets:2: smtp://bar:***@gnu.org
As you see, even in that case the tool hides the actual password part
by replacing it with three asterisks. If you are working in a secure
environment, you can tell mu wicket to show passwords as
well, by supplying the -v option twice.
A counterpart of --verbose is the --quite
(-q) option, which instructs wicket to suppress any
output, excepting error messages. This can be used in scripts, which
analyze the mailutils wicket exit code to alter the control flow.
The mailutils wicket tool exits with code 0 if all URLs were
matched and with code 1 if some of them were not matched in the ticket
file. If an error occurred, the code 2 is returned.
The mailutils dbm tool manages DBM files using libmu_dbm
The invocation syntax is:
mailutils dbm subcommand [options] file [keys]
or
mailutils dbm [options] subcommand file [keys]
where subcommand selects the operation mode, options modify the tool behavior and file specifies the DBM file to operate upon. Some commands allow for optional keys to be specified.
The file argument can be either a DBM file name or a Database URL.
The create subcommand and its synonym load instruct the tool to create a new database:
mailutils dbm create file.db
If the argument file already exists, it will be truncated prior to adding new records to it.
The data to populate the database with are read from the standard
input. The mailutils dbm command supports several formats for
these data, which are discussed later. In the simplest case (a so
called ‘format 0.0’) each input line must consist of two fields
separated by any amount of whitespace. The first field is treated as
a key and the second one as the corresponding value.
The usual way to read data from a file is, of course, by redirecting the file to the standard input as in:
mailutils dbm create file.db < input.txt
There is also a special option for that purpose: --file (-f). Thus, the following command is equivalent to the one above:
mailutils dbm create --file input.txt file.db
The --file option has the advantage that it allows, in conjunction with another options, for copying input file metadata (owner UID, GID and file mode) to the created database. For example, the following command ensures that the created database file will have the same metadata as the input file:
mailutils dbm create --file input.txt --copy-permissions file.db
The --copy-permissions (-P) option is the one that does the job.
There are also other ways to control mode and ownership of the created database, which are described below.
More advanced dump formats (e.g. ‘version 1.0’ format) carry additional information about the file, including its original name, ownership and mode. If input is in one of these formats, the file name argument becomes optional. If it is not supplied, the name stored in the input stream will be used. For example, supposing that the file users.dump is in format 1.0, the following command suffices to restore the original filename, ownership, mode and, of course, data:
mailutils dbm create --file users.dump
The add subcommand adds records to a database. Records are read from the standard input and must be formatted as for create:
mailutils dbm add file.db
If the argument file does not exist, it will be created.
Adding a record with a key which is already present in the database produces an error. To replace existing records, use the replace subcommand instead.
The same options that affect the behavior of create apply to add and ‘replace’ as well, e.g.:
mailutils dbm replace --file input.txt --copy-permissions file.db
To delete records, use the delete subcommand. It reads a list of keys to delete to be specified as arguments in the command line:
mailutils dbm delete file.db foo bar
The command above will delete from file.db records with keys ‘foo’ and ‘bar’.
It is not an error to attempt to delete a key that does not exist in the database, although such use will produce a warning message.
By default, keys are matched literally. It is also possible to use various pattern matching techniques, depending on the option specified.
The --glob (-G) option instructs the tool to use UNIX globbing pattern matching. For example, the command below will delete all keys starting with ‘foo’ and ending with a decimal digit:
mailutils dbm delete file.db 'foo*[0-9]'
(note the quoting necessary to prevent shell from interpreting the metacharacters itself).
Another option, --regex (-R) instructs mailutils
to treat supplied keys as extended regular expressions:
mailutils dbm delete --regex file.db 'foo.*[0-9]{1,3}'
Both options are affected by the --ignore-case (-i) option, which turns on case-insensitive matching.
Using pattern matching to delete records can be a risky operation as selecting a wrong pattern will lead to removing wrong records. It is recommended to first use the list mode described below to verify that the patterns match the right keys.
The list command lists the content of the database:
mailutils dbm list file.db
By default, entire content is listed on the standard output.
If supplied more than one command line argument, this mode treats the rest of arguments after the database file name as the keys to look for and lists only records with these keys:
$ mailutils dbm list file.db foo bar foo 1 bar 56
The --glob and --regex options instruct the tool to use UNIX globbing or extended regular expression matching, correspondingly. These were described in detail above.
The dump subcommand dumps the database to the standard output in a format suitable for backup or sending over the network (a version 1.0 format).
mailutils dbm dump file.db < file.dump
The produced file is suitable for input to the create (load) command. Among other uses, it provides an easy way to convert databases between various formats supported by Mailutils. For example this is how to convert the database file file.db to the GDBM database new.db:
mailutils dbm dump file.db | mailutils dbm create gdbm://new.db
Both list and dump subcommands share the same set of options. In fact, they are pretty similar, except that use different defaults. The list subcommand is designed to produce a human-readable output, whereas the dump subcommand is oriented towards backup purposes.
As of version 3.14, mailutils dbm supports two formats
for dumping DBM databases. Both formats are line-oriented. Comments
are introduced with a sharp (‘#’) sign in the column 0 of a line,
followed by at least one white space character (space or tab). Sharp
sign followed by a colon (‘#:’) introduces a pragmatic
comment, which carries some additional information to the loader.
The version 0.0 format is suitable for databases whose records contain only ASCII data. In this format, each record occupies a separate line, which consists of the key and value separated by a single TAB character. Empty lines are ignored. For example:
$ mailutils list /etc/mail/users.db root guessme smith pAssword qed fooBar
The output in version 0.0 format is human readable and can be used as input to the popauth utility (see popauth. However, version 0.0 has serious drawbacks. First of all, it is not suitable for databases that contain binary data. Secondly, it cannot properly handle keys beginning with a sharp sign or containing TAB. The version 1.0 format is free from these drawbacks.
The version 1.0 dump format begins with a header
containing important information about the file, such as its file
name, ownership and file mode. This information is stored in
pragmatic comments and allows mailutils dbm load to easily recreate
an exact copy of the file. The following comments are defined:
Indicates that the data that follow are in version 1.0 format.
Original database file name, without directory parts.
Owner UID.
Owner name.
Owner GID
Owner group name.
File mode in octal
Following this header are actual data. Each record is output in two parts: key and value. Each part begins with a ‘#:len=n’ construct on a line by itself, where n is the length of the data in decimal. This line is followed by one or more lines of the actual data, encoded in base64. The data are formatted so that each line does not exceed 76 bytes in length (not counting the terminating newline). An example of this format follows:
# Database dump file created by GNU Mailutils 2.99.93 on # Tue Nov 1 13:28:03 2011 #:version=1.0 #:file=users.db #:uid=0,user=root,gid=25,group=mail,mode=640 #:len=6 c21pdGgA #:len=9 cEFzc3dvcmQA #:len=5 cm9vdAA= #:len=8 Z3Vlc3NtZQA= #:len=4 cWVkAA== #:len=7 Zm9vQmFyAA==
The table below summarizes exit codes used by mailutils dbm:
| Code | Symbolic name | Meaning |
|---|---|---|
| 0 | EX_OK | Successful termination |
| 64 | EX_USAGE | Command line usage error |
| 65 | EX_DATAERR | Error in user-supplied data: the input file is badly formatted, or some of the data supplied in the command line are invalid (e.g. user name, uid or the like), etc. |
| 66 | EX_NOINPUT | Cannot open input file |
| 67 | EX_NOUSER | No such user or UID when trying to set output file ownership |
| 69 | EX_UNAVAILABLE | Operation cannot be performed due to some kind of problem (e.g. access to the file denied, etc.) |
| 70 | EX_SOFTWARE | Internal software error |
| 74 | EX_IOERR | Input/output error |
The mailutils logger tool logs information using Mailutils log facility.
Syntax:
mailutils logger [options] [message]
The message argument, if supplied, gives the text to log. If not supplied, the utility reads lines of text from standard input or a file (if the --file option is given) and sends them to log:
# Send text to log $ mailutils logger I am here # Log each line from file.txt $ mailutils logger --file file.txt # Read stdin and log it: $ mailutils logger
The default logging channel is bound to standard error. To bind it to
syslog, use the --syslog command line option. In that case
mailutils uses facility ‘user’ and priority ‘err’. You
can change this by using the --priority (-p) option.
Its argument is either a syslog facility name or facility and severity
names separated by a dot. For example, the following invocation will use
facility ‘auth’, severity ‘info’:
mailutils logger --priority auth.info
The syslog tag can be set using the --tag (-t) option:
mailutils logger --tag myprog
The default tag is ‘mu-logger’.
The --severity (-s) option sets the Mailutils severity level. Its argument can be any of the following: ‘debug’, ‘info’, ‘notice’, ‘warning’, ‘error’, ‘crit’, ‘alert’, ‘emerg’.
Finally, the --locus (-l) option binds log messages to a location in a file. Its argument has the following syntax:
file:line[:col]
where file is the file name, line is the line number and optional col is the column number in that file.
For example, the following invocation:
mailutils logger --locus mailutils.conf:34 Suspicious statement
will send the following to the log:
mu-logger: mailutils.conf:34: Suspicious statement
The mailutils pop command invokes an interactive POP3 client shell.
It reads commands from the standard input, executes them and displays
the results on the standard output. If the standard input is
connected to a terminal, the readline and history facilities are
enabled (provided that Mailutils is configured with GNU Readline).
The mailutils pop commands form two major groups. POP3 protocol
commands interact with the remote POP3 server and display responses
obtained from it. These commands are named after their POP3
equivalents. Another group, internal commands, are used to
configure the shell itself.
Open connection to hostname. If the -tls option is given, TLS encryption (also known as POPS protocol) will be used. If port argument is not given, the command uses port 110 for a plain POP connection or 995 for POPS (if -tls is given).
Start TLS negotiation. This command is valid only after successful
unencrypted connection has been initiated (using connect
without -tls argument).
Send user name to the server. The pass command must follow.
Send password. This command is valid only after user. If
the password argument is omitted, the shell will ask you to
enter it. While entering, both echoing and history recording will be
disabled. Use this to avoid compromising your password.
Authenticate with APOP. If the password argument is omitted, you will be asked to supply it. While entering, both echoing and history recording will be disabled.
List server capabilities. Any number of arguments is accepted. If given, the shell will display only the named capabilities, otherwise it displays entire list. By default capa reuses the response of its previous invocation (if there was any), instead of resending the ‘CAPA’ command to the server. To force it do so, use the -reread option.
Send a ‘NOOP’ (no operation) command to the server.
Get the mailbox size and number of messages in it.
Shows unique message identifiers. Without arguments, shows identifiers for each message in the mailbox. If number is given, the command returns the UIDL of that particular message only.
Lists messages. See above for the meaning of number. Each line
of the produced listing contains describes a single message and
contains at least the message number and size in bytes. Depending on
the POP3 server implementation, additional fields may be present. For
example, Mailutils pop3d can also output number of lines in
the message in the additional third field.
Retrieve a message.
Display message headers and first number (default 5) of lines of its body.
Mark message for deletion.
Remove deletion marks.
Quit pop3 session.
Close existing connection.
Control output verbosity. Without arguments the verbose
command shows current settings.
The argument ‘off’ (the default) turns off all additional output. The ‘verbose on’ command enables POP3 protocol tracing output. Additional arguments can be used to provide more verbosity. The ‘secure’ argument enables display of user passwords in the trace output and the ‘payload’ argument enables showing payload data (e.g. response body sent in the reply to ‘RETR’ command, etc.) Thus, the full diagnostics output is obtained by
verbose on secure payload
The ‘mask’ and ‘unmask’ arguments allow to disable and enable such additional verbosity. For example, supposing the command above is in action, the following command will suppress the display of user passwords in the traces:
verbose mask secure
Similarly, verbose unmask secure will turn it back again.
Set command prompt. The argument can contain variable references in any of the following forms:
$name
${name}
where name is the variable name. Such references are expanded to the actual value of the variable at the time of expansion. The following variables are defined:
| Variable | Expansion |
|---|---|
| user | Login name of the authenticated POP3 user. If the session is not authenticated yet, expands to ‘[nouser]’. |
| host | Name of the remote host, or ‘[nohost]’ if no connection is established. |
| program-name | Name of the program, as typed on the command line to invoke it. |
| canonical-program-name | ‘mailutils’ |
| package | ‘Mailutils’ |
| version | Mailutils version number (3.14) |
| status | Session status. One of: ‘disconnected’, ‘connected’ or ‘logged in’. |
For example:
prompt "[${user}@$host "
Notice the use of quotes to include the space character in the prompt.
Exit the program.
Without arguments displays a list of commands with possible arguments and short descriptions.
With one argument, displays a terse description for the given command.
Shows command history.
The mailutils imap command invokes an interactive IMAP4 client
shell. It reads commands from the standard input, executes them and
displays the results on the standard output. The shell is similar to
the mailutils pop (see mailutils pop) shell.
Most commands in this group correspond (with minor differences) to IMAP commands described in RFC 35015.
Opens connection to the server host. If the -tls option is given, TLS encryption (also known as IMAPS protocol) will be used. If port argument is not supplied, the command uses port 143 for a plain IMAP connection or 993 for IMAPS (if -tls is given).
Lists server capabilities. Any number of names is accepted. If
at least one is given, the shell will display only the named
capabilities, otherwise it displays the entire list. By default,
capability reuses the response of its previous invocation
(if there was any), instead of resending the CAPABILITY command to the
server. To force it do so, use the -reread option.
Starts TLS negotiation. This command is valid only after unencrypted connection has been successfully initiated using connect without the -tls option.
Logs in to the server as user with optional password. If the pass argument is omitted, the shell will ask you to enter it. While entering, both echoing and history recording will be disabled. Use this to avoid compromising your password.
Quits the imap session.
Sends IMAP ID command. See RFC 29716, for a discussion of arguments. By default, this command outputs entire ID list. If, however, the -test option is given, it will check whether the keyword kw is defined and display its value if so.
Requests a server checkpoint.
Selects the named mailbox. Without argument, selects ‘INBOX’.
Examines the named mailbox, i.e. selects it in read-only mode. If mbox is not given, ‘INBOX’ is assumed.
Gets mailbox status. Valid keywords (kw arguments) are: ‘MESSAGES’, ‘RECENT’, ‘UIDNEXT’, ‘UIDVALIDITY’, and ‘UNSEEN’. Keywords are case-insensitive.
Fetches message data. See RFC 3501, section 6.4.57, for a discussion of its arguments.
Alters mailbox data. See RFC 3501, section 6.4.68, for a discussion of its arguments.
Closes the currently selected mailbox (with expunge).
Closes the currently selected mailbox (without expunge).
Deletes the mailbox mbox.
Renames existing mailbox old-name to new-name.
Permanently removes messages marked for deletion.
Creates new mailbox with the given name.
Reads an RFC-822 message from file and appends it to the mailbox. Use the -time option to supply envelope date for the message. Use the -flag option to supply message flags. For example:
append -time "25-Aug-2002 18:00:00 +0200" -flag \Seen INBOX input.msg
Lists matching mailboxes. See RFC 3501, section 6.3.89, for a discussion of its arguments.
Lists subscribed mailboxes (RFC 3501, section 6.3.910).
Subscribes to a mailbox.
Removes mailbox mbox from the subscription list.
Sends a no operation command.
Closes existing connection.
The imap shell implements the same set of internal commands as
pop shell: See Internal commands. There is
only one imap-specific internal command:
Controls the UID mode. When the UID mode is on, the commands
fetch and store operate on and return message UIDs
instead of their sequence numbers.
To examine the current state of the UID mode, issue the uid
command without arguments.
Reads an RFC-822 message from a file and sends it over to a specified SMTP server. The syntax is:
mailutils send [options] host file
where host defines the SMTP server through which to send the message, and file is the name of the input file containing the message. For example, to send a message from file input.msg using SMTP service at localhost, one would write:
$ mailutils send localhost input.msg
The host argument can be an IP address, hostname, or a valid SMTP URL.
The following command line options are understood:
Supplies envelope sender address.
Supplies envelope recipient address. It can be specified multiple times.
Instructs the program to read recipient email addresses from the message ‘To:’, ‘Cc:’, and ‘Bcc:’ headers.
The mailutils smtp command invokes an interactive SMTP client
shell. It reads commands from the standard input, executes them and
displays the results on the standard output. If the standard input is
connected to a terminal, the readline and history facilities are
enabled (provided that Mailutils is configured with GNU Readline).
Connects to SMTP server at host (IP address or host name). If the -tls option is given, TLS encryption (also known as SMTPS protocol) will be used. The default port number is 25 for plain SMTP and 465 for SMTPS. Explicit port argument overrides the default value.
A number of parameters is associated with an open connection:
Domain name used in EHLO statement. Defaults to the current host name.
The following parameters are used for ESMTP authentication:
User name.
User password.
GSASL service name.
Realm name.
Host name.
SMTP URL. It can contain all of the above. Default is smtp://
These parameters are manipulated using the following statements:
Sets parameter param to value. Several parameters can be
set with one set statement.
Unset the supplied connection parameters. If used without arguments, unsets all parameters.
Lists the values of the connection parameters. If used without arguments, lists all parameters.
Sends the ESMTP greeting. Unless domain is supplied, the connection parameter ‘domain’ is used.
Lists the server capabilities.
Initiates encrypted connection. This command is disabled if the connection is opened with the -tls option.
Authenticate using the supplied mechanisms.
Reset the session state.
Sets sender email address. If used without arguments, prints the sender email address.
Sets recipient email address. If used without arguments, prints all recepient names collected so far.
Sends the command with its arguments verbatim.
Quits the SMTP session.
Reads the message from file and sends it. If file is not
supplied, the action depends on whether a send command was used
prevously within the same session. If so, mailutils will
first ask whether to reuse the already supplied message. If not, it
will start an editor, allowing you to enter the new message. When you
exit from the editor, you will be prompted what to do with the
message: send, edit, or quit (discard) it.
Internal commands are the same as in pop shell: See Internal commands.
This command fixes attributes and UID assignments in ‘maildir’ mailboxes created by mailutils versions prior to 3.10.90.
Attribute flags used in ‘maildir’ mailboxes by these versions of
mailutils were a bit different from those described in the original
description of the ‘maildir’ format11
and those used by another implementations. The discrepancy has been
reported in the Mailutils bug tracker12
and was fixed in version 3.10.90. Along with this fix, measures has
been taken to ensure persistence of UID assignments between different
sessions. Starting from version 3.10.90, whenever mailutils
library opens a maildir mailbox, it determines the version that
created it. If the mailbox is writable and the library determines
that the mailbox is affected by the two problems described above, it
fixes the mailbox on the fly. This process is completely transparent
to the user.
If you operate a site with a large number of mailboxes in
‘maildir’ formats, you may choose to fix up all of them at once.
That’s what the maildir_fixup command is for. It takes one
or more directory names as its arguments and recursively scans these
directories in search for ‘maildir’ mailboxes. Each mailbox
found is analyzed and a fix-up is performed, if necessary. If a
mailbox is already in the new format, it remains untouched.
The following options modify the program’s behavior:
List each maildir name before processing it.
Don’t touch maildirs, just print their names,
The maildir_fixup tool reads main mailutils configuration
file by default. It looks for program-specific settings in the
section ‘program maildir_fixup’. If the include statement
is present that has a directory name as its argument, the file
maildir_fixup is looked up in that directory and parsed, if
present.
The program uses the following configuration statements:
| Statement | Reference |
|---|---|
| debug | See debug statement. |
| locking | See locking statement. |
| mandatory-locking | See mandatory-locking statement. |
A stand-alone mailbox-locking utility. It is the default program used
by mailutils if the locking.type configuration
statement is set to external (see external locking type).
The program usage syntax is:
# To lock mbox: dotlock options mbox # To unlock it: dotlock -u options mbox
By default the program implements the ‘dotlock’ locking (see dotlock locking type). This can be changed either in the configuration file, or via the command line options.
The following common configuration statements affect the behavior of
dotlock:
| Statement | Reference |
|---|---|
| debug | See Debug Statement. |
| locking | See Locking Statement. |
The program understands the following command line options:
Print details of failure reasons to stderr.
If a lock file exists and is more than n minutes old, forcibly remove it and re-lock the mailbox. Default n is 10 minutes.
Check if the PID of lock owner is still active. If not, break the lock.
Number of times to retry acquiring the lock, if it is held by another process. The default is 10 times.
Sets delay in seconds between two successive locking attempts. The default is 1 second.
Unlock the mailbox.
For backward compatibility, map can be a string containing colon-delimited list of mappings. Such usage is, however, deprecated.
In case of Copy and Save, message sender is
used instead
Rmail does not use this feature
The exact location is determined at
configuration time by setting environment variable
DEFAULT_CUPS_CONFDIR. On most sites running
./configure DEFAULT_CUPS_CONFDIR=/etc/cups
should be recommended.
See http://www.faqs.org/rfcs/rfc3501.html.
http://www.faqs.org/rfcs/rfc2971.html
http://tools.ietf.org/html/rfc3501#section-6.4.5
http://tools.ietf.org/html/rfc3501#section-6.4.6
http://tools.ietf.org/html/rfc3501#section-6.3.8
http://tools.ietf.org/html/rfc3501#section-6.3.9
http://cr.yp.to/proto/maildir.html
GNU Mailutils Manual (split by chapter):
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.