GNU Mailutils Manual

Table of Contents

GNU Mailutils

This edition of the GNU Mailutils Manual, last updated on 5 November 2016, documents GNU Mailutils Version 3.0.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Top   Up: Top   FastForward: Mailbox   Contents: Table of ContentsIndex: Function Index

1 Introduction

GNU Mailutils is a set of libraries and utilities for handling electronic mail. It addresses a wide audience and can be of interest to application developers, casual users and system administrators alike.

It provides programmers with a consistent API allowing them to handle a variety of different mailbox formats transparently and without having to delve into complexities of their internal structure. While doing so, it also provides interfaces that simplify common programming tasks, such as handling lists, parsing configuration files, etc. The philosophy of Mailutils is to have a single and consistent programming interface for various objects designed to handle the same task. It tries to use their similarities to create an interface that hides their differences and complexities. This covers a wide variety of programming tasks: apart from mailbox handling, Mailutils also contains a unified iterface for work with various DBM databases and much more.

The utilities built upon these libraries share that same distinctive feature: no matter what is the internal structure of an object, it is always handled the same way as other objects that do the same task. Again, the most common example of this approach are, of course, mailboxes. Whatever Mailutils program you use, you can be sure it is able to handle various mailbox formats. You even don’t have to inform it about what type a mailbox is: it will do its best to discover it automatically.

This approach sometimes covers entities which are seldom regarded as compatible. For example, using Mailutils it is possible to treat an SMTP connection as a mailbox opened only for appending new messages. This in turn, provides a way for extending the functionality of some utilities. As an example, using this concept of mailboxes, the usual mail delivery agent becomes able to do things usually reserved for mail transport agents only!

At the core of Mailutils is libmailutils, a library which provides an API for accessing a generalized mailbox. A set of complementary libraries provide methods for handling particular mailbox implementations: UNIX mailbox, Maildir, MH, POP3, IMAP4, even SMTP. Mailutils offers functions for almost any mail-related task, such as parsing of messages, email addresses and URLs, handling MIME messages, listing mail folders, mailcap facilities, extensible Sieve filtering, access control lists. It supports various modern data security and authentication techniques: TLS encryption, SASL and GSSAPI, to name a few. Mailutils is able to work with a wide variety of authorization databases, ranging from traditional system password database up to RADIUS, SQL and LDAP.

The utilities provided by Mailutils include imap4d and pop3d mail servers, mail reporting utility comsatd, general-purpose mail delivery agent maidag, mail filtering program sieve, an implementation of MH message handling system and much more.

All utilities share the same subset of command line options and use a unified configuration mechanism, which allows to easily configure the package as a whole.

This software is part of the GNU Project and is copyrighted by the Free Software Foundation. All libraries are distributed under the terms of the Lesser GNU Public License. The documentation is licensed under the GNU FDL, and everything else is licensed under the GNU GPL.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Introduction   Up: Introduction   FastForward: Mailbox   Contents: Table of ContentsIndex: Function Index

1.1 What this Book Contains

This book addresses a wide audience of both system administrators and users that aim to use Mailutils programs, and programmers who wish to use Mailutils libraries in their programs. Given this audience, the book is divided in three major parts.

The first part provides a detailed description of each Mailutils utility, and advices on how to use them in various situations. This part is intended for users and system administrators who are using Mailutils programs. If you are not interested in programming using Mailutils, this is the only part you need to read.

Subsequent parts address programmers.

The second part is a tutorial which provides an introduction to programming techniques for writing mail applications using GNU Mailutils.

Finally, the third part contains a complete Mailutils library reference.

This version of the book is not finished. The places that may contain inaccurate information carry prominent notices stating so. For updated versions of the documentation, visit http://mailutils.org/manual. All material that ends up in this document is first published in the Mailutils Wiki, available at http://mailutils.org/wiki. Be sure to visit it for latest updates.

If you have any questions that are not answered there, feel free to ask them at the mailing list bug-mailutils@gnu.org.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Introduction   Up: Introduction   FastForward: Mailbox   Contents: Table of ContentsIndex: Function Index

1.2 A bit of History, and why use this package?

Editor’s note:

The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised.

This package started off to try and handle large mailbox files more gracefully then available at that time POP3 servers did. While it handles this task, it also allows you to support a variety of different mailbox formats without any real effort on your part. Also, if a new format is added at a later date, your program will support that new format automatically as soon as it is compiled against the new library.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Introduction   Up: Top   FastForward: Programs   Contents: Table of ContentsIndex: Function Index

2 Mailbox

The principal object Mailutils operates on is mailbox – a collection of mail messages. The two main characteristics of a mailbox are its type and path. The type defines how the messages are stored within a mailbox. The path specifies the location of the mailbox. The two characteristics are usually combined within a Uniform Resource Locator (URL), which uniquely identifies the mailbox. The syntax for URL is:

type:[//[user:password@]host[:port]]path[?query][;params]

The square brackets do not appear in a URL, instead they are used to denote optional parts.

Not all parts are meaningful for all types. Their usage and purpose are described in the sections that follow.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Mailbox   Up: Mailbox   FastForward: Programs   Contents: Table of ContentsIndex: Function Index

2.1 Local Mailboxes

Local mailboxes store mail in files on the local file system. A local mailbox URL is:

type://path[;params]

The path defines its location in the file system. For example:

mbox:///var/spool/mail/gray

Optional params is a semicolon-separated list of optional arguments that configures indexed directory structure. See local URL parameters, for a detailed description.

The local mailbox types are:

mbox

A traditional UNIX mailbox format. Messages are stored sequentially in a single file. Each message begins with a ‘From’ line, identifying its sender and date when it was received. A single empty line separates two adjacent messages.

This is the default format.

maildir

The Maildir mailbox format. Each message is kept in a separate file with a unique name. Each mailbox is therefore a directory. This mailbox format eliminates file locking and makes message access much faster.

This format was originally described by D. J. Bernstein in http://cr.yp.to/proto/maildir.html.

mh

MH Message Handling System format. Each message is kept in a separate file named after its sequential numeric identifier within the mailbox. Deleted messages are not removed, but instead the corresponding file is renamed by prepending a comma to its original name. Each mailbox is a directory. Mailboxes can be nested.

This format was originally developed by RAND Corporation. Mailutils implementation is compatible both with the original implementation and with its descendant nmh.

file

This type can be used when accessing an existing mailbox of any of the formats defined above. The actual mailbox format is determined automatically. This type is assumed when a mailbox is referred to by its full pathname.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Mailbox   Up: Mailbox   FastForward: Programs   Contents: Table of ContentsIndex: Function Index

2.2 Remote Mailboxes

Remote mailboxes are accessed via one of the remote message protocols.

The basic remote mailbox types are:

pop

Remote mailbox accessed using the Post Office Protocol (POP3). Default port number 110.

The URL is:

pop://[user[:pass][;auth=+APOP]@]host[:port][;notls]

The host gives the name or IP address of the host running a POP3 server. Optional port can be used to connect to a port other than the default 110.

The user and pass supply authentication credentials. If any of them is missing, Mailtils will first try to obtain it from the ticket file. If that fails, the behavior depends on the type of the controlling terminal. If the terminal is a tty device (i.e. the program accessing the mailbox was started from the command line), it will ask the user to supply the missing credentials. Otherwise it will issue an appropriate error message and refuse to access the mailbox.

By default, the usual POP3 authentication is used. The ‘auth=+APOP’ authentication parameter instructs Mailutils to use APOP authentication instead.

If the server offers the STLS capability, Mailutils will attempt to establish encrypted TLS connection. The ‘notls’ parameter disables this behavior.

pops

Remote mailbox accessed using the Post Office Protocol (POP3). The transmission channel is encrypted using the transport layer security (TLS). The default port is 995.

The URL is:

pops://[user[:pass][;auth=+APOP]@]host[:port]

The meaning of its components is the same as for ‘pop’ type.

imap

Remote mailbox accessed via the Internet Message Access Protocol. Default port number is 143.

The URL is:

imap://[user[:pass]host[:port][;notls]

The host gives the name or IP address of the host running a IMAP4 server. Optional port can be used to connect to a port other than the default 143.

The user and pass supply authentication credentials. If any of them is missing, Mailtils will first try to obtain it from the ticket file. If that fails, the behavior depends on the type of the controlling terminal. If the terminal is a tty device (i.e. the program accessing the mailbox was started from the command line), it will ask the user to supply the missing credentials. Otherwise it will issue an appropriate error message and refuse to access the mailbox.

If the server offers the STARTTLS capability, Mailutils will attempt to establish encrypted TLS connection. The ‘notls’ parameter disables this behavior.

imaps

The ‘imaps’ type differs in that its transmission channel is encrypted using the transport layer security (TLS). The default port is 993.

The URL is:

imaps://[user[:pass]@]host[:port]

The meaning of its components is the same as for ‘imap’ type.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Mailbox   Up: Mailbox   FastForward: Programs   Contents: Table of ContentsIndex: Function Index

2.3 SMTP Mailboxes

SMTP mailboxes types are special remote mailboxes that allow only append operation. Appending a message is equivalent to sending it to the given recipient or recipients.

smtp

A remote mailbox accessed using the Simple Message Transfer Protocol.

The SMTP URL syntax is:

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

The host gives the name or IP address of the host running SMTP server. Optional port can be used to connect to a port other than the default 25.

The user, pass, and ‘auth=’ elements supply credentials for ESMTP authentication, if the server supports it.

If the ESMTP authentication is used, Mailutils will select the best authentication mechanism from the list offered by the server. To force it to use a particular authentication mechanism, use the ‘auth’ authentication parameter. Its value is a comma-separated list of authentication mechanisms, in the order from the most to the least preferred one, e.g.:

smtp://smith:guessme;auth=cram-md5,digest-md5@localhost

Optional params is a semicolon-separated list of additional parameters. Valid parameters are:

domain=string

Append ‘@string’ to those recipient addresses that lack the domain part.

from=addr

Use addr as sender address.

noauth

Disable ESMTP authentication.

notls

Disable TLS.

recipient-headers[=name[,name...]]

Use the supplied header names to determine recipient addresses. When no values are supplied, disables header scanning.

strip-domain

Strip domain part from all recipient addresses.

to=addr[,addr...]

Deliver messages to the supplied email addresses.

smtps

A remote mailbox accessed using the Simple Message Transfer Protocol, with the transmission channel encrypted using the transport layer security (TLS). The default port is 465.

The URL is

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

See the ‘smtp’ type for a detailed description of its types. The only difference from ‘smtp’ is that the ‘notls’ parameter is not used.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Mailbox   Up: Mailbox   FastForward: Programs   Contents: Table of ContentsIndex: Function Index

2.4 Program Mailboxes

Program mailboxes support only append operation. Appending a message is performed by invoking the specified program and passing the message to its standard input stream.

A ‘sendmail’ mailbox is identified by the following URL:

sendmail[://path]

The messages are sent by invoking sendmail binary with the -oi -t options. If the message being appended has the ‘From:’ header, its value is passed to sendmail using the -f option.

The default path to the sendmail binary is system-dependent. The path part can be used to specify it explicitly.

The ‘prog’ mailbox URL is:

prog://pathname[?query]

Messages are appended by invoking the program pathname with the arguments supplied by query. The latter is a list of words delimited by ‘&’ characters.

Arguments can contain the following variables (see Variables):

sender

Expands to the sender email address.

rcpt

Expands to comma-separated list of email addresses obtained from ‘To:’, ‘Cc:’ and ‘Bcc:’ headers of the message.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Mailbox   Up: Top   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3 Mailutils Programs

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.1 Command Line

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: command line   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.1.1 Basic Notions About Command Line Options

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: command line   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.1.2 Options That are Common for All Utilities.

All GNU Mailutils programs understand a common subset of options.

--help
-?

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.

--usage

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.

--version
-V

Print program version and exit.

--show-config-options

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.

--config-file=file

Load this configuration file, instead of the default.

--config-help

Show configuration file summary.

--config-lint

Check configuration file syntax and exit

--config-verbose

Verbosely log parsing of the configuration files.

--no-site-config

Do not load site-wide configuration file.

--no-user-config

Do not load user configuration file.

--no-config

Don’t load site-wide and user configuration files.

--set=path=value

Set configuration variable. See the --set option.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2 Mailutils Configuration File

Configuration files are the principal means of configuring any GNU Mailutils component. When started, each utility tries to load its configuration from the following locations, in that order:

  1. Main site-wide configuration file.

    It is named sysconfdir/mailutils.conf, where sysconfdir stands for the system configuration directory set when compiling the package. You can obtain the value of sysconfdir by running

    $ mailutils info sysconfdir
    

    or

    $ prog --show-config-options | grep SYSCONFDIR
    

    where prog stands for any GNU Mailutils utility.

    The site-wide configuration file is not read if any of --no-site-config or --no-config command line options was given.

    Older versions of GNU Mailutils read configuration from file mailutils.rc. To facilitate transition, mailutils will look for that file as well. If both the default site-wide configuration file and legacy configuration file are present you will get the following warning:

    legacy configuration file /etc/mailutils.rc ignored
    

    Otherwise, if mailutils.conf does not exist and mailutils.rc is present, it will be used instead and the following warning will be issued:

     using legacy configuration file /etc/mailutils.rc:
     please rename it to /etc/mailutils.conf
    
  2. Per-user configuration file.

    Client utilities, such as frm or sieve, look in the user home directory for a file named ‘.prog’, where prog is the name of the utility. If present, this file will be loaded after loading the site-wide configuration file. For example, the per-user configuration file for sieve utility is named .sieve.

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

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

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

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

Neither site-wide nor user configuration files are required to exist. If any or both of them are absent, GNU Mailutils won’t complain – the utility will silently fall back to its default settings.

To make configuration processing more verbose, use the --config-verbose command line option. Here is an example of what you might get using this option:

imap4d: parsing file `/etc/mailutils.conf'
imap4d: finished parsing file `/etc/mailutils.conf'

Specifying this option more than once adds more verbosity to this output. If this option is given two times, GNU Mailutils will print each configuration file statement it parsed, along with the exact location where it occurred (the exact meaning of each statement will be described later in this chapter):

imap4d: parsing file `/etc/mailutils.conf'
# 1 "/etc/mailutils.conf"
mailbox {
# 2 "/etc/mailutils.conf"
  mailbox-pattern maildir:/var/spool/mail;type=index;param=2;user=${user};
# 3 "/etc/mailutils.conf"
  mailbox-type maildir;
};
# 6 "/etc/mailutils.conf"
include /etc/mailutils.d;
imap4d: parsing file `/etc/mailutils.d/imap4d'
...

To test configuration file without actually running the utility, use the --config-lint command line option. With this option, any Mailutils utility exits after finishing parsing of the configuration files. Any errors occurred during parsing are displayed on the standard error output. This option can be combined with --config-verbose to obtain more detailed output.

The --config-help command line option produces on the standard output the summary of all configuration statements understood by the utility, with detailed comments and in the form suitable for configuration file. For example, the simplest way to write a configuration file for, say, imap4d is to run

$ imap4d --config-help > imap4d.conf

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

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

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

$ imap4d --set .logging.syslog=no

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

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.1 Configuration File Syntax

The configuration file consists of statements and comments.

There are three classes of lexical tokens: keywords, values, and separators. Blanks, tabs, newlines and comments, collectively called white space are ignored except as they serve to separate tokens. Some white space is required to separate otherwise adjacent keywords and values.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: conf-syntax   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.1.1 Comments

Comments may appear anywhere where white space may appear in the configuration file. There are two kinds of comments: single-line and multi-line comments. Single-line comments start with ‘#’ or ‘//’ and continue to the end of the line:

# This is a comment
// This too is a comment

Multi-line or C-style comments start with the two characters ‘/*’ (slash, star) and continue until the first occurrence of ‘*/’ (star, slash).

Multi-line comments cannot be nested. However, single-line comments may well appear within multi-line ones.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: conf-syntax   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.1.2 Statements

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

The following is a simple statement:

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

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

A value can be one of the following:

number

A number is a sequence of decimal digits.

boolean

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

unquoted string

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

quoted string

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

SequenceReplaced with
\aAudible bell character (ASCII 7)
\bBackspace character (ASCII 8)
\fForm-feed character (ASCII 12)
\nNewline character (ASCII 10)
\rCarriage return character (ASCII 13)
\tHorizontal tabulation character (ASCII 9)
\vVertical tabulation character (ASCII 11)
\\A single backslash (‘\’)
\"A double-quote.

Table 3.1: Backslash escapes

In addition, the sequence ‘\newline’ is removed from the string. This allows to split long strings over several physical lines, e.g.:

"a long string may be\
 split over several lines"

If the character following a backslash is not one of those specified above, the backslash is ignored and a warning is issued.

Two or more adjacent quoted strings are concatenated, which gives another way to split long strings over several lines to improve readability. The following fragment produces the same result as the example above:

"a long string may be"
" split over several lines"
Here-document

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

The <<word construct instructs the parser to read all the following lines up to the line containing only word, with possible trailing blanks. Any lines thus read are concatenated together into a single string. For example:

<<EOT
A multiline
string
EOT

The body of a here-document is interpreted the same way as a double-quoted string, unless word is preceded by a backslash (e.g. ‘<<\EOT’) or enclosed in double-quotes, in which case the text is read as is, without interpretation of escape sequences.

If word is prefixed with - (a dash), then all leading tab characters are stripped from input lines and the line containing word. Furthermore, if - is followed by a single space, all leading whitespace is stripped from them. This allows to indent here-documents in a natural fashion. For example:

<<- TEXT
    The leading whitespace will be
    ignored when reading these lines.
TEXT

It is important that the terminating delimiter be the only token on its line. The only exception to this rule is allowed if a here-document appears as the last element of a statement. In this case a semicolon can be placed on the same line with its terminating delimiter, as in:

help-text <<-EOT
        A sample help text.
EOT;
list

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

alias (test,null);

In any case where a list is appropriate, a single value is allowed without being a member of a list: it is equivalent to a list with a single member. This means that, e.g.

alias test;

is equivalent to

alias (test);

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

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

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: conf-syntax   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.1.3 Statement Path

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

For example, consider the following file:

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

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

.foo.bar.baz

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

.foo.baz

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

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

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

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

is identified by the following pathname:

.program=x.bar.baz

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

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

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

--set .logging.facility=mail

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

logging {
    facility mail;
}

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

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

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

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

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

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

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

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

or

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.2 Configuration Variables

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

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

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

${variable:-word}

Use Default Values. If variable is unset or null, the expansion of word is substituted. Otherwise, the value of variable is substituted.

${variable:=word}

Assign Default Values. If variable is unset or null, the expansion of word is assigned to variable. The value of variable is then substituted.

${variable:?word}

Display Error if Null or Unset. If variable is null or unset, the expansion of word (or a message to that effect if word is not present) is output to the current logging channel. Otherwise, the value of variable is substituted.

${variable:+word}

Use Alternate Value. If variable is null or unset, nothing is substituted, otherwise the expansion of word is substituted.

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.3 The include Statement

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

include file;

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

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

It is a common to end the site-wide configuration file with an include statement, e.g.:

include /etc/mailutils.d;

This allows each particular utility to have its own configuration file. Thus, imap4d will read /etc/mailutils.d/imap4d, etc.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.4 The program statement

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

program progname {
   ...
}

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

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.5 The logging Statement

Syntax

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

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

Description

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

Configuration: syslog bool

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

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

$ mailutils info log_facility
Configuration: facility name

Use syslog facility name. Valid argument values are: ‘user’, ‘daemon’, ‘auth’, ‘authpriv’, ‘mail’, ‘cron’, ‘local0’ through ‘local7’ (all names case-insensitive), or a facility number.

Configuration: tag text

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

Configuration: print-severity bool

Print Mailutils severity name before each message.

Configuration: severity name

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

Configuration: session-id bool

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.6 The debug Statement

Syntax

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

Description

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

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.7 The mailbox Statement

Syntax

mailbox {
  # Use specified url as a mailspool.
  mail-spool url;
  
  # Create mailbox url using pattern.
  mailbox-pattern pattern;
  
  # Default mailbox type.
  mailbox-type type;
  
  # Default user mail folder.
  folder dir;
}

Description

The mailbox statement configures the location, name and type of user mailboxes.

The mailbox location can be specified using mail-spool or mail-pattern statements.

Configuration: mail-spool path

The mail-spool statement specifies directory that holds user mailboxes. Once this statement is given, the libmailutils library will assume that the mailbox of user login is kept in file path/login.

Historically, path can contain mailbox type prefix, e.g.: ‘maildir:///var/spool/mail’, but such usage is discouraged in favor of mailbox-pattern statement.

Configuration: mailbox-pattern url

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

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

Optional URL parameters can be used to configure indexed directory structure. Such structure is a special way of storing mailboxes, which allows for faster access in case of very large number of users.

By default, all user mailboxes are stored in a single directory and are named after user login names. To find the mailbox for a given user, the system scans the directory for the corresponding file. This usually implies linear search, so the time needed to locate a mailbox is directly proportional to the ordinal number of the mailbox in the directory.

GNU Mailutils supports three types of indexed directories: ‘direct’, ‘reverse’, and ‘hashed’.

In direct indexed directory structure, path contains 26 subdirectories named with lower-case letters of Latin alphabet. The location of the user mailbox is determined using the following algorithm:

  1. Take the first letter of the user name.
  2. Map it to a lower-case letter using index mapping table. The result gives the name of a sub-directory where the mailbox is located.
  3. Descend into this directory.

For example, using this algorithm, the mailbox of the user ‘smith’ is stored in file path/s/smith.

If each of single-letter subdirectories contains the indexed directory structure, we have second level of indexing. In this case the file name of ‘smith’’s mailbox is path/s/m/smith.

The reverse indexed structure uses the same principles, but the indexing letters are taken from the end of the user name, instead of from the beginning. For example, in the 2nd level reverse indexed structure, the ‘smith’’s mailbox is located in path/h/t/smith.

Finally, the hashed structure consists of 256 subdirectories under path, named by 2-letter hex codes from ‘00’ to ‘FF’. Mailboxes are stored in these subdirectories. The name of the subdirectory is computed by hashing first level letters of the user name. The hashing algorithm is:

  1. Take next letter from the user name
  2. Add its ASCII value to the hash sum.
  3. Continue (1-2) until level letters are processed, or all letters from the file name are used, whichever occurs first.
  4. Convert the computed sum modulo 256 to a hex code.

Indexed directory structures are configured using the following arguments:

type=value

Specifies the type of indexing. Valid values are ‘index’, for direct indexed structure, ‘rev-index’ for reverse indexing, and ‘hash’ for hashed structure.

param=number

Specifies indexing level.

user=string

Specifies indexing key. The only meaningful value, as of Mailutils version 3.0 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:

  1. If environment variable FOLDER is set, use its value.
  2. Otherwise, if environment variable MAIL is set, use its value.
  3. If neither of these is set, construct the mailbox name by concatenating the built-in mail spool directory name, a directory separator, and the user name.

    The built-in mail spool directory name is determined at compile time, using the ‘_PATH_MAILDIR’ define from the include file paths.h. If this value is not defined, /var/mail or /usr/spool/mail is used.

Configuration: mailbox-type type

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

Configuration: folder dir

Sets user mail folder directory. Its value is used when expanding ‘plus-notation’, i.e. such mailbox names as +inbox. The ‘+’ sign is replaced by dir, followed by a directory separator (‘/’).

The dir argument can contain mailbox type prefix, e.g ‘mh://Mail’.

The default folder name is ‘Mail/’.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.8 The locking Statement

Syntax

locking {
  # Default locker flags.
  flags arg;
  
  # Set timeout for acquiring the lock.
  retry-timeout arg;
  
  # Set the maximum number of times to retry acquiring the lock.
  retry-count number;
  
  # Expire locks older than this amount of time.
  expire-timeout number;
  
  # Use prog as external locker program.
  external-locker prog;
}

Description

This block statement configures various parameters used when locking UNIX mailboxes in order to prevent simultaneous writes.

It is important to note, that locking applies only to traditional UNIX mailboxes (see mbox). All other mailbox types don’t require locking.

Configuration: flags string

Set locking flags. Argument is a string consisting of one or more of the following letters:

E

Use an external program to manage locks. The program is given by the external-locker statement (see below).

R

If the locking attempt failed, retry it. This is the default. The number of retries, and time interval between the two successive attempts is given by retry-count and retry-timeout statements, correspondingly.

T

If a lock file exists, check its modification time and, if it is older than a predefined amount of time, remove the lock. The amount of time is specified by expire-timeout statement.

P

Store the PID of the locking process in a lock file.

Configuration: retry-count number

Number of locking attempts. The ‘P’ flag must be set for this to take effect.

Configuration: retry-timeout seconds

Time interval, in seconds, between the two successive locking attempts. The ‘P’ flag must be set for this to take effect.

Configuration: expire-timeout seconds

Remove existing lock file, if it is created more than this number of seconds ago. The ‘T’ flag must be set for this to take effect.

Configuration: external-locker string

Determines the external locker program to use. The string argument is the valid command line, starting with the full program name. The ‘E’ flag must be set for this to take effect.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.9 The mailer Statement

Syntax

mailer {
  url url;
}

Description

A mailer is a special logical entity GNU Mailutils uses for sending messages. Its internal representation is discussed in Mailer. The mailer statement configures it.

The mailer statement contains a single sub-statement:

Configuration: url str

Set the mailer URL.

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

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

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

sendmail[://progname]

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

-oi

Do not treat ‘.’ as message terminator.

-f addr

Use addr as the sender address.

-t

Get recipient addresses from the message.

See sendmail, for details.

prog://progname?query

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

It is described in detain in prog.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.10 The acl Statement

Syntax

acl {
  # Allow connections from this IP address.
  allow [from] ip;
  
  # Deny connections from this IP address.
  deny [from] ip;
  
  # Log connections from this IP address.
  log [from] ip [string];
  
  /* Execute supplied program if a connection from this
     IP address is requested. */
  exec [from] ip program;
  
  /* Use program to decide whether to allow connection
     from ip. */
  ifexec [from] ip program;
}

Description

The ACL statement defines an Access Control List, a special structure that controls who can access the given Mailutils resource.

The acl block contains a list of access controls. Each control can be regarded as a function that returns a tree-state value: ‘True’, ‘False’ and ‘Don't know’. When a remote party connects to the server, each of controls is tried in turn. If a control returns ‘False’, access is denied. If it returns ‘True’, access is allowed. If it returns ‘Don't know’, then the next control is tried. It is unclear whether to allow access if the last control in list returned ‘Don't know’. GNU Mailutils 3.0 issues a warning message and allows access. This default may change in future versions. Users are advised to write their ACLs so that the last control returns a 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:

Configuration: allow [from] cidr

Allow connections from IP addresses matching this cidr block.

Configuration: deny [from] cidr

Deny connections from IP addresses matching this cidr block.

Configuration: ifexec [from] cidr program

When a connection from the cidr block is requested, execute the program program. If its exit code is ‘0’, then allow connection. Otherwise, deny it.

The program argument undergoes variable expansion and word splitting. The following variables are defined:

aclno

Ordinal number of the control in the ACL. Numbers begin from ‘1’.

family

Connection family. Mailutils version 3.0 supports the following families: ‘AF_INET’, ‘AF_INET6’ and ‘AF_UNIX’.

address

Remote IP address (for ‘AF_INET’ and ‘AF_INET6’) or socket name (for ‘AF_UNIX’). Notice that most Unixes return empty string instead of the ‘AF_UNIX’ socket name, so do not rely on it.

port

Remote port number (for ‘AF_INET’ and ‘AF_INET6’).

Configuration: exec [from] cidr program

If a connection from the cidr block is requested, execute the given program. Do not wait for it to terminate, and ignore its exit code. The program is subject for variable expansion as in ‘ifexec’.

The following two controls are provided for logging purposes and as a means of extensions. They always return a ‘Don't know’ answer, and therefore should not be used at the end of an ACL:

Configuration: log [from] cidr [string]

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

If string is not given, the format of the log entry depends on the connection family, as described in the table below:

{AF_INET ip:port}

For inet IPv4 connections. The variables ip and port are replaced by the remote IP address and port number, correspondingly.

{AF_UNIX}

For connections over UNIX sockets. The socket name, if available, may be printed before the closing curly brace.

If string is supplied, it undergoes variable expansions as described for the ‘ifexec’.

For example, the following ACL makes a Mailutils server log every incoming connection:

  acl {
     log from any "Connect from ${address}";
     ...
  }

This was the default behavior for the versions of Mailutils up to ‘1.2’, so if you got used to its logs you might wish to add the above in your configuration files.

Configuration: exec [from] cidr program

If a connection from the cidr block is requested, execute the given program. Do not wait for it to terminate, and ignore its exit code.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.11 The tcp-wrappers Statement

Syntax

tcp-wrappers {
  # Enable TCP wrapper access control.
  enable bool;
  
  # Set daemon name for TCP wrapper lookups.
  daemon name;
  
  # Use file for positive client address access control.
  allow-table file;
  
  # Use file for negative client address access control.
  deny-table file;
}

Description

The tcp-wrappers statements provides an alternative way to control accesses to the resources served by GNU Mailutils. This statement is enabled if Mailutils is compiled with TCP wrappers library libwrap.

Access control using TCP wrappers is based on two files, called tables, containing access rules. There are two tables: the allow table, usually stored in file /etc/hosts.allow, and the deny table, kept in file /etc/hosts.deny. The rules in each table begin with an identifier called daemon name. A utility that wishes to verify a connection, selects the entries having its daemon name from the allow table. A connection is allowed if it matches any of these entries. Otherwise, the utility retrieves all entries with its daemon name from the deny table. If any of these matches the connection, then it is refused. Otherwise, if neither table contains matching entries, the connection is allowed.

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

Configuration: enable bool

Enable access control using TCP wrappers. It is on by default.

Configuration: daemon name

Set daemon name for TCP wrapper lookups. By default, the name of the utility is used. E.g. imap4d uses ‘imap4d’ as the daemon name.

Configuration: allow-table file

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

Configuration: deny-table file

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.12 Server Settings

GNU Mailutils offers several server applications: pop3d, imap4d, comsatd, to name a few. Being quite different in their purpose, they are very similar in some aspects of their architecture. First of all, they all support two operating modes: daemon, where a program disconnects from the controlling terminal and works in background, and inetd, where it remains in foreground and communicates with the remote party via standard input and output streams. Secondly, when operating as daemons, they listen to a preconfigured set of IP addresses and ports, reacting to requests that arrive.

To configure these aspects of functionality, GNU Mailutils provides Server Configuration Settings, which is describes in this subsection.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Server Settings   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.12.1 General Server Configuration


Syntax:

# Set daemon mode.
mode ‘inetd|daemon’;

# Run in foreground.
foreground bool;

# Maximum number of children processes to run simultaneously.
max-children number;

# Store PID of the master process in file.
pidfile file;

# Default port number.
port portspec;

# Set idle timeout.
timeout time;

Description: These statements configure general server-related issues.

Configuration: mode string;

Set operation mode of the server. Two operation modes are supported:

daemon

Run as a standalone daemon, disconnecting from the controlling terminal and continuing to run in the background. In this case, it is the server that controls what IP addresses and ports to listen on, who is allowed to connect and from where, how many clients are allowed to connect simultaneously, etc. Most remaining configuration statements are valid only in the daemon mode.

This is the preferred mode of operation for GNU Mailutils servers.

inetd

Operate as a subprocess of UNIX internet super-server program, inetd. See Internet super-server in inetd(8) man page, for a detailed description of the operation of inetd and its configuration. In this case it is inetd that controls all major connectivity aspects. The Mailutils server program communicates with it via standard input and output streams.

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

Configuration: foreground bool;

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

Configuration: max-children number;

[daemon mode only]
Set maximum number of child processes allowed to run simultaneously. This equals the number of clients that can use the server simultaneously.

The default is 20 clients.

Configuration: pidfile file;

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

Configuration: port portspec;

[daemon mode only]
Set default port to listen to. The portspec argument is either a port number in decimal, or a symbolic service name, as listed in /etc/services (see Internet network services list in services(5) man page).

Configuration: timeout time;

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Server Settings   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.12.2 The server Statement


Syntax:

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

  # Set idle timeout.
  timeout time;

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

  # Kind of TLS encryption to use for this server.
  tls ‘no’|‘ondemand’|‘required’|‘connection’;
    
  # Set server specific ACLs.
  acl { /* See ACL Statement. */ };
}

Description:

The server block statement configures a single TCP or UDP server. It takes effect only in daemon mode (see server mode). The argument to this statement specifies the IP address, and, optionally, the port, to listen on for requests. The ipaddr part is either an IPv4 address in dotted-quad form, or a IPv6 address enclosed in square brackets, or a symbolic host name which can be resolved to such an address. Specifying ‘0.0.0.0’ as the ipaddr means listen on all available network interfaces. The port argument is either a port number in decimal, or a symbolic service name, as listed in /etc/services (see Internet network services list in services(5) man page). If port is omitted, Mailutils uses the port set by port statement (see port), or, in its absence, the default port number, which depends on a server being used (e.g. 110, for pop3d, 143, for imap4d, etc.).

Any number of server statements may be specified in a single configuration file, allowing to set up the same service on several IP addresses and/or port numbers, and with different configurations.

Statements within the server block statement configure this particular server.

Configuration: single-process bool;

If set to true, this server will operate in single-process mode. This mode is intended for debugging only, do not use it on production servers.

Configuration: transcript bool;

Enable transcript of the client-server interaction. This may generate excessive amounts of logging, which in turn may slow down the operation considerably.

Session transcripts are useful in fine-tuning your configurations and in debugging. They should be turned off on most production servers.

Configuration: timeout time;

Set idle timeout for this server. This overrides the global timeout settings (see timeout).

Configuration: backlog number;

Configures the size of the queue of pending connections

Configuration: tls mode;

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

no

TLS is not used. The corresponding command (STLS, for POP3, STARTTLS, for IMAP4) won’t be available even if the TLS configuration is otherwise complete.

ondemand

TLS is initiated when the user issues the appropriate command. This is the default when TLS is configured.

required

Same as above, but the use of TLS is mandatory. The authentication state is entered only after TLS negotiation has succeeded.

connection

TLS is always forced when the connection is established. For pop3d this means using POP3S protocol (or IMAP4S, for imap4d).

Configuration: acl

This statement defines a per-server Access Control List. Its syntax is as described in ACL Statement. Per-server ACLs complement, but not override, global ACLs, i.e. if both global ACL and per-server ACL are used, the connection is allowed only if both of them allow it, and is denied if any one of them denies it.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.13 The auth Statement

Syntax

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

Description

Some mail utilities provide access to their services only after verifying that the user is actually the person he is claiming to be. Such programs are, for example, pop3d and imap4d. The process of the verification is broken down into two stages: authorization and authentication. In authorization stage the program retrieves the information about a particular user. In authentication stage, this information is compared against the user-supplied credentials. Only if both stages succeed is the user allowed to use the service.

A set of modules is involved in performing each stage. For example, the authorization stage can retrieve the user description from various sources: system database, SQL database, virtual domain table, etc. Each module is responsible for retrieving the description from a particular source of information. The modules are arranged in a module list. The modules from the list are invoked in turn, until one of them succeeds or the list is exhausted. In the latter case the authorization fails. Otherwise, the data returned by the succeeded module are used in authentication.

Similarly, authentication may be performed in several ways. The authentication modules are also grouped in a list. Each module is tried in turn until either a module succeeds, in which case the authentication succeeds, or the end of the list is reached.

For example, the authorization list

  (system, sql, virtdomains)

means that first the system user database (/etc/password) is searched for a description of a user in question. If the search fails, the SQL database is searched. Finally, if it also fails, the search is performed in the virtual domain database.

Note, that some authentication and/or authorization modules may be disabled when configuring the package before compilation. The names of the disabled modules are nevertheless available for use in runtime configuration options, but they represent a “fail-only” functionality, e.g. if the package was compiled without SQL support then the module ‘sql’ in the above example will always fail, thus passing the execution on to the next module.

The auth statement configures authentication and authorization.

Configuration: authorization module-list

Define a sequence of modules to use for authorization. Modules will be tried in the same order as listed in module-list.

The modules available for use in authorization list are:

system

User credentials are retrieved from the system user database (/etc/password).

sql

User credentials are retrieved from a SQL database. A separate configuration statement, sql, is used to configure it (see sql statement).

virtdomain

User credentials are retrieved from a “virtual domain” user database. Virtual domains are configured using virtdomain statement (see virtdomain statement).

radius

User credentials are retrieved using RADIUS. See radius statement, for a detailed description on how to configure it.

ldap

User credentials are retrieved from an LDAP database. See ldap statement, for an information on how to configure it.

Unless overridden by authorization statement, the default list of authorization modules is:

  1. generic
  2. system
  3. pam
  4. sql
  5. virtual
  6. radius
  7. ldap
Configuration: authentication module-list

Define a sequence of modules to use for authentication. Modules will be tried in the same order as listed in module-list.

The following table lists modules available for use in module-list:

generic

The generic authentication type. User password is hashed and compared against the hash value returned in authorization stage.

system

The hashed value of the user password is retrieved from /etc/shadow file on systems that support it.

sql

The hashed value of the user password is retrieved from a SQL database using query supplied by getpass statement (see getpass).

pam

The user is authenticated via pluggable authentication module (PAM). The PAM service name to be used is configured in pam statement (see pam statement).

radius

The user is authenticated on a remote RADIUS server. See radius statement.

ldap

The user is authenticated using LDAP. See ldap statement.

Unless overridden by authentication statement, the list of authentication modules is the same as for authorization, i.e.:

  1. generic
  2. system
  3. pam
  4. sql
  5. virtual
  6. radius
  7. ldap

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.14 PAM Statement

Syntax

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

Description

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

Configuration: service text

Define service name to look for in PAM configuration. By default, the base name of the Mailutils binary is used.

This statement takes effect only if ‘pam’ is listed in authentication statement (see auth statement).

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.15 The virtdomain Statement

Syntax

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

Description

Virtual mail domains make it possible to handle several mail domains each having a separate set of users, on a single server. The domains are completely independent of each other, i.e. the same user name can be present in several domains and represent different users.

When authenticating to a server with virtual domain support enabled, users must supply their user names with domain parts. The server strips off the domain part and uses it as a name of UNIX-format password database file, located in the domain password directory. The latter is set using passwd-dir statement.

Configuration: passwd-dir dir

Set virtual domain password directory.

For example, when authenticating user ‘smith@example.com’, the server will use password file named dir/example.com. This file must be in UNIX passwd format (see password file in passwd(5) man page), with encrypted passwords stored in it (as of GNU Mailutils version 3.0, there is no support for shadow files in virtual password directories, although this is planned for future versions). Here is an example record from this file:

smith:Wbld/G2Q2Le2w:1000:1000:Email Account:/var/mail/domain/smith:/dev/null

Notice, that it must contain user names without domain parts.

The pw_dir field (the 6th field) is used to determine the location of the maildrop for this user. It is defined as pw_dir/INBOX. In our example, the maildrop for user ‘smith’ will be located in file /var/mail/domain/smith.

If user did not supply his domain name, or if no matching record was found in the password file, or if the file matching the domain name does not exist, then GNU Mailutils falls back to alternative method. First, it tries to determine the IP address of the remote party. Then the domain name corresponding to that address is looked up in the DNS system. Finally, this domain name is used as a name of the password file.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.16 The radius Statement

Syntax

radius {
  # Set radius configuration directory.
  directory dir;
  # Radius request for authorization.
  auth request;
  # Radius request for getpwnam.
  getpwnam request;
  # Radius request for getpwuid.
  getpwuid request;
}

Description

The radius block statement configures RADIUS authentication and authorization.

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

Configuration: directory dir

Set full path name to the GNU Radius configuration directory.

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

AttributeTypeDescription
GNU-MU-User-NamestringUser login name
GNU-MU-UIDintegerUID
GNU-MU-GIDintegerGID
GNU-MU-GECOSstringGECOS
GNU-MU-DirstringHome directory
GNU-MU-ShellstringUser shell
GNU-MU-MailboxstringUser mailbox
GNU-MU-QuotaintegerMail quota (in bytes)

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

$INCLUDE dict/mailutils.dict

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

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

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

user

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

User-Name = ${user}
passwd

User password. For examples:

User-Password = ${passwd}
Configuration: auth pairlist

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

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

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

Configuration: getpwnam pairlist

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

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

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

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

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

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

Configuration: getpwuid pairlist

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

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

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.17 The sql Statement

Syntax

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

Description

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

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

Configuration: interface type

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

mysql

Interface with a MySQL server (http://www.mysql.org).

odbc

Use ODBC interface. See http://www.unixodbc.org, for a detailed description of ODBC configuration.

postgres

Interface with a PostgreSQL server (http://www.postgres.org).

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

Configuration: host arg

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

Configuration: port arg

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

Configuration: db arg;

Name of the database.

Configuration: user arg

SQL user name.

Configuration: passwd arg;

Password to access the database.

Configuration: password-encryption arg;

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

plain

Password is in plain text.

crypt
hash

Password is encrypted by system crypt function (see crypt in crypt(3) man page).

scrambled

Password is encrypted by MySQL password function.

Configuration: getpwnam query

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

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

name

User name.

passwd

User password.

uid

UID of the user.

gid

GID of the primary group.

gecos

Textual description of the user.

dir

User’s home directory

shell

User’s shell program.

The following columns are optional:

mailbox

Full pathname of the user’s mailbox. If not returned or NULL, the mailbox is determined using the default algorithm (see Mailbox).

quota

Upper limit on the size of the mailbox. The value is either an integer number optionally followed by one of the usual size suffixes: ‘K’, ‘M’, ‘G’, or ‘T’ (case-insensitive).

Configuration: getpwuid query

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

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

Configuration: getpass query

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

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

Configuration: field-map list

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

field-map (uid=user_id);

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.18 The ldap Statement

Syntax

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

Description

The ldap statement configures the use of LDAP for authentication.

Configuration: enable bool

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

Configuration: url url

Sets the URL of the LDAP server.

Configuration: base string

Defines base DN for LDAP lookups.

Configuration: binddn string

Defines the DN for accessing LDAP database.

Configuration: passwd string

Password for use when binding to the database.

Configuration: tls bool

Enable the use of TLS when connecting to the server.

Configuration: debug number

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

Configuration: field-map map

Defines a map for parsing LDAP replies. The map is a list of 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:

name

User name.

passwd

User password.

uid

UID of the user.

gid

GID of the primary group.

gecos

Textual description of the user.

dir

User’s home directory

shell

User’s shell program.

The default mapping is

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

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

  (&(objectClass=posixAccount) (uid=$user))
Configuration: getpwuid string

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

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.19 The tls Statement

Syntax

tls {
  # Enable TLS support.
  enable bool;
  # Specify SSL certificate file.
  ssl-cert string;
  # Specify SSL certificate key file.
  ssl-key file;
  # Specify trusted CAs file.
  ssl-cafile file;
  # Set the priorities to use on the ciphers, methods, etc.
  ssl-priorities string;
  # Configure safety checks for SSL key file.
  key-file-safety-checks list;
  # Configure safety checks for SSL certificate.
  cert-file-safety-checks list;
  # Configure safety checks for SSL CA file.
  ca-file-safety-checks list;
}

Description

Configuration: enable bool

Enable TLS support. If absent, ‘enable On’ is assumed.

Configuration: ssl-cert string

Specify SSL certificate file.

Configuration: ssl-key file

Specify SSL certificate key file.

Configuration: ssl-cafile file

Specify the trusted certificate authorities file.

Configuration: ssl-priorities string

Set the priorities to use on the ciphers, key exchange methods, MACs and compression methods.

Configuration: key-file-safety-checks list

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

none

Disable all checks.

all

Enable all checks.

gwrfil

Forbid group writable files.

awrfil

Forbid world writable files.

grdfil

Forbid group readable files.

ardfil

Forbid world writable files.

linkwrdir

Forbid symbolic links in group or world writable directories.

gwrdir

Forbid files in group writable directories.

awrdir

Forbid files in world writable directories,

Configuration: cert-file-safety-checks list

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

Configuration: ca-file-safety-checks list

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: configuration   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.2.20 The gsasl Statement

Editor’s note:

This node is to be written.

Syntax

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.3 Debugging

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:

error

Displays error conditions which are normally not reported, but passed to the caller layers for handling.

trace0 through trace9

Ten levels of verbosity, ‘trace0’ producing less output, ‘trace9’ producing the maximum amount of output.

prot

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: debugging   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.3.1 Level Syntax

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:

!category

Disables all levels for the specified category.

category

Enables all levels for the specified category.

category.level

For the given category, enables all levels from ‘error’ to level, inclusive.

category.=level

Enables only the given level for this category.

category.!level

Disables all levels from ‘error’ to level, inclusive, for this category.

category.!=level

Disables only the given level in this category.

category.levelA-levelB

Enables all levels in the range from levelA to levelB, inclusive.

category.!levelA-levelB

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: debugging   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.3.2 BNF

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"

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: debugging   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.3.3 Debugging Categories

acl

This category enables debugging of Access Control Lists. Available levels are:

error

As usual, displays errors, not directly reported otherwise.

trace0

Basic tracing of ACL processing.

trace9

Traces the process of matching the ACL conditions.

config

This category affects configuration parser and/or lexical analyzer. The following levels are supported:

trace0

Minimal information about configuration statements.

trace2

Trace lexical structure of the configuration files.

trace7

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
mailbox

Operations over mailboxes. This module supports the following levels: ‘error’, ‘trace0’, ‘trace1’, and ‘prot’. The latter is used by remote mailbox support libraries.

auth

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
mailer

Debugs mailer operations. The following levels are supported:

error

Displays mild error conditions.

trace0

Traces mailer operations in general: displays what part of the message is being sent, etc.

trace6

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.

trace7

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.

prot

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

serve

This category provides debugging information for Mailutils IP server objects. It supports the ‘error’ and ‘trace0’ levels.

folder

This category controls debugging information shown for operations related to Mailutils folders.

remote

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:

trace6

Show security-sensitive information (user passwords, etc.)

trace7

Show payload information

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.4 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:

StatementReference
debugSee debug statement.
tlsSee tls statement.
mailboxSee mailbox statement.
lockingSee locking statement.

frm

The 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:

-d
--debug

Enable debugging output.

-f string
--field string

Display the header named by string instead of From Subject pair.

-l
--to

Include the contents of To header to the output. The output field order is then: To From Subject.

-n
--number

Prefix each line with corresponding message number.

-Q
--Quiet

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.

-q
--query

Print a message only if there are unread messages in the mailbox.

-S
--summary

Print a summary line.

-s attr
--status attr

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.

-t
--align

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

from

The 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:

-c
--count

Prints only a count of messages in the mailbox and exit.

-d
--debug

Prints additional debugging output.

-s string
--sender=string

Prints only mail whose ‘From:’ headers contain the supplied string.

-f url
--file=url

Examine mailbox from the given url.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5 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 standard /bin/mail program. As well as its predecessor, it can be used either in sending mode or in reading mode. Mail enters sending mode when one or more email addresses were specified in this 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 to read and manipulate the contents of the user system mailbox. The --file (-f) command line option allows to specify another mailbox name. For more detail, see Reading Mail.

In addition to the Mailutils configuration file, mail loads the traditional ‘mailrc’-style configuration files. See Mail Configuration Files, for a detailed description of their format.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.1 Invoking mail

General 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:

-A file
--attach=file

Attach file to the composed message. The encoding and content type are controlled by the --encoding and --content-type options, correspondingly.

-a header:value
--append=header:value

Append the given header to the composed message.

--content-type=type

This options sets the content type to be used by all subsequent --attach options.

-E command
--exec=command

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.

-e
--exist

Return true if the mailbox contains some messages. Return false otherwise.

This is useful for writing shell scripts.

--encoding=enc

Sets content transfer encoding for use by the subsequent --attach options.

-F
--byname

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. This option sets the ‘byname’ variable, which see (see byname).

-f
--file

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.

-H
--headers

Print header summary to stdout and exit.

-i
--ignore

Ignore interrupts when composing the message.

-N
--nosum

Do not display initial header summary.

-n
--norc

Do not read the system-wide mailrc file. See Mail Configuration Files.

-p
--print
--read

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.

-q
--quit

Cause interrupts to terminate program.

-r address
--return-address=address

Sets the return email address for outgoing mail. See return-address.

-s subj
--subject=subj

Send a message with a Subject of subj. Valid only in sending mode.

-t
--to

Read recipients from the message header. Ignore addresses listed in the command line.

-u user
--user=user

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.2 How to Specify Message Sets

Many mail commands such as print and delete can be given a message list to operate upon. Wherever the message list is omitted, the command operates on the current message.

The message list 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

Message Number

This specifier addresses the message with the given ordinal number in the mailbox.

Message range

Message range is specified as two message numbers separated by a dash. It selects all messages with the number lying within that range.

Attribute specifier

An Attribute specifier is a colon followed by a single letter. The Attribute specifier addresses all messages in the mailbox that have the given attribute. These are the valid attribute specifiers:

:d

Selects all deleted messages.

:n

Selects all recent messages, i.e. the messages that have not been neither read not seen so far.

:o

Selects all messages that have been seen.

:r

Selects all messages that have been read.

:u

Selects all messages that have not been read.

:t

Selects all tagged messages.

:T

Selects all untagged messages.

Header match

The header match is a string in the form:

[header:]/string/

It selects all messages that contain header field header matching given regexp. If the variable regexp is set, the string is assumed to be a POSIX regexp. Otherwise, a header is considered to match string if the latter constitutes a substring of the former (comparison is case-insensitive).

If header: part is omitted, it is assumed to be ‘Subject:’.

Message body match

The message body match is a string in the form:

:/string/

It selects all messages whose body matches the string. The matching rules are the same as described under “Header match”.

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:

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.3 Composing Mail

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Composing Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.3.1 Quitting Compose Mode

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Composing Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.3.2 Getting Help on Compose Escapes: ~?

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Composing Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.3.3 Editing the Message: ~e and ~v

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Composing Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.3.4 Modifying the Headers: ~h, ~t, ~c, ~b, ~s

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Composing Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.3.5 Enclosing Another Message: ~m and ~M

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Composing Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.3.6 Adding a File to the Message: ~r and ~d

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Composing Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.3.7 Attaching a File to the Message

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
   1 myfile.html text/html base64

Each line of the listing contains the ordinal number of the attachment, the name of the file, content-type and transfer encoding used.

The ‘~^’ escape removes attachments. Its argument is the number of the attachment to remove, e.g.:

~^ 1

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Composing Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.3.8 Printing And Saving the Message

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Composing Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.3.9 Signing the Message: ~a and ~A

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Composing Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.3.10 Printing Another Message: ~f and ~F

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Composing Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.3.11 Inserting Value of a Mail Variable: ~i

The ‘~i’ escape enters the value of the named mail variable into the body of the message being composed.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Composing Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.3.12 Executing Other Mail Commands: ~: and ~-

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Composing Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.3.13 Executing Shell Commands: ~! and ~|

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.4 Reading Mail

To read messages from a given mailbox, use one of the following ways of invoking mail:

mail

To read messages from your system mailbox.

mail -f
mail --file

To read messages from your mailbox ($HOME/mbox). If the --user option (see below) is also given, read messages from that user’s mbox.

mail -f path_to_mailbox
mail --file path_to_mailbox

To read messages from the specified mailbox.

mail -u user
mail --user=user

To read messages from the system mailbox belonging to user.

Please note, that usual mailbox permissions won’t allow you to use the last variant of invocation, unless you are a super-user. Similarly, the last but one variant is also greatly affected by the permissions the target mailbox has.

Notice that path_to_mailbox is not an argument to --file (-f) option, but rather the first non-optional argument on the command line. Therefore, 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

Unless you have started mail with --norc command line option, it will read the contents of the system-wide configuration file. Then it reads the contents of user configuration file, if any. For detailed description of these files, see Mail Configuration Files. After this initial setup, mail displays the first page of header lines and enters interactive mode. In interactive mode, mail displays its prompt (‘?’, if not set otherwise) and executes the commands the user enters.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Reading Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.4.1 Quitting the Program

Following commands quit the program:

quit

Terminates the session. If mail was operating upon user’s system mailbox, then all undeleted and unsaved messages that have been read and are not marked with hold flag are saved to the user’s mbox file ($HOME/mbox). The messages, marked with delete are removed. The program exits to the Shell, unless saving the mailbox fails, in which case user can escape with the exit command.

exit
ex
xit

Program exits to the Shell without modifying the mailbox it operates upon.

Typing EOF (‘C-D’) alone is equivalent to ‘quit’.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Reading Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.4.2 Obtaining Online Help

Following commands can be used during the session to request online help:

help [command]
hel [command]
? [command]

Display detailed command synopsis. If no command is given, help for all available commands is displayed.

list
*

Print a list of available commands.

version
ve

Display program version.

warranty
wa

Display program warranty statement.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Reading Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.4.3 Moving Within a Mailbox

^

Move to the first undeleted message.

$

Move to the last undeleted message.

next
n

Move to the next message.

previous
prev

Move to the previous message.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Reading Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.4.4 Changing Mailbox/Directory

cd [dir]
chdir [dir]
ch [dir]

Change to the specified directory. If dir is omitted, $HOME is assumed.

file [mailbox]
fi [mailbox]
folder [mailbox]
fold [mailbox]

Read in the contents of the specified mailbox. The current mailbox is updated as if quit command has been issued. If mailbox is omitted, the command prints the current mailbox name followed by the summary information regarding it, e.g.:

& fold
"/var/spool/mail/gray": 23 messages 22 unread

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Reading Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.4.5 Controlling Header Display

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.

discard [header-field-list]
di [header-field-list]
ignore [header-field-list]
ig [header-field-list]

Add header-field-list to the ignored list. When used without arguments, this command prints the contents of ignored list.

retain [header-field-list]
ret [header-field-list]

Add header-field-list to the retained list. When used without arguments, this command prints the contents of retained list.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Reading Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.4.6 Displaying Information

=

Displays the current message number.

headers [msglist]
h [msglist]

Lists the current pageful of headers.

from [msglist]
f [msglist]

Lists the contents of ‘From’ headers for a given set of messages.

z [arg]

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.

size [msglist]
si [msglist]

Lists the message number and message size in bytes for each message in msglist.

folders

Displays the value of folder variable.

summary
su

Displays current mailbox summary. E.g.:

& summary
"/var/spool/mail/gray": 23 messages 22 unread

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Reading Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.4.7 Displaying Messages

print [msglist]
p [msglist]
type [msglist]
t [msglist]

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.

Print [msglist]
P [msglist]
Type [msglist]
T [msglist]

Like print but also prints out ignored header fields.

decode [msglist]
dec [msglist]

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
...
top [msglist]
to [msglist]

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 [msglist] [shell-command]
| [msglist] [shell-command]

Pipe the contents of specified messages through shell-command. If shell-command is empty but the string variable cmd is set, the value of this variable is used as a command name.

struct [msglist]

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Reading Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.4.8 Marking Messages

tag [msglist]
ta [msglist]

Tag messages. The tagged messages can be referred to in message list using ‘:t’ notation.

untag [msglist]
unt [msglist]

Clear tags from specified messages. To untag all messages tagged so far type

& untag :t
hold [msglist]
ho [msglist]
preserve [msglist]
pre [msglist]

Marks each message to be held in user’s system mailbox. This command does not override the effect of delete command.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Reading Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.4.9 Disposing of Messages

delete [msglist]
d [msglist]

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.

undelete [msglist]
u [msglist]

Clear delete mark from the specified messages.

dp [msglist]
dt [msglist]

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Reading Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.4.10 Saving Messages

save [[msglist] file]
s [[msglist] file]

Takes a message list and a file name or mailbox URL and appends each message in turn to the end of that file or mailbox. Mailbox URLs begin with mailbox type specifier, such as ‘mbox://’, ‘maildir://’, etc. The name of file or 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.

Save [msglist]
S [msglist]

Like save, but the file to append messages to is named after the sender of the first message in msglist. 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.

write [[msglist] file]
w [[msglist] file]

Similar to save, except that only message body (without the header) is saved.

Write [msglist]
W [msglist]

Similar to Save, except that only message body (without the header) is saved.

mbox [msglist]
mb [msglist]
touch [msglist]
tou [msglist]

Mark list of messages to be saved in the user’s mailbox ($HOME/mbox) upon exiting via quit command. This is the default action for all read messages, unless you have variable hold set.

copy [[msglist] file]
c [[msglist] file]

Similar to save, except that saved messages are not marked for deletion.

Copy [msglist]
C [msglist]

Similar to Save, except that saved messages are not marked for deletion.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Reading Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.4.11 Editing Messages

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.

edit [msglist]
e [msglist]

Edits each message in msglist with the editor, specified in EDITOR environment variable.

visual [msglist]
v [msglist]

Edits each message in msglist with the editor, specified in VISUAL environment variable.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Reading Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.4.12 Aliasing

alias [alias [address...]]
a [alias [address...]]
group [alias [address...]]
g [alias [address...]]

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.

unalias [alias...]
una [alias...]

Takes a list of names defined by alias commands and discards the remembered groups of users. The alias names no longer have any significance.

alternates name...
alt name...

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Reading Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.4.13 Replying

mail [address...]
m [address...]

Switches to compose mode. After composing the message, sends messages to the specified addresses.

reply [msglist]
respond [msglist]
r [msglist]

For each message in msglist, switches to compose mode and sends the composed message to the sender and all recipients of the message.

Reply [msglist]
Respond [msglist]
R [msglist]

Like reply, except that the composed message is sent only to originators of the specified messages.

Notice, that setting mail variable flipr (see Mail Variables) swaps the meanings of the two above commands, so that reply sends the message to the sender and all recipients of the message, whereas Reply sends it to originators only.

followup [msglist]
fo [msglist]

Switches to compose mode. After composing, sends the message to the originators and recipients of all messages in msglist.

Followup [msglist]
F [msglist]

Similar to followup, but reply message is sent only to originators of messages in msglist.

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Reading Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.4.14 Controlling Sender Fields

Commands sender and nosender are used to manipulate the contents of the sender field 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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Reading Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.4.15 Incorporating New Mail

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Reading Mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.4.16 Shell Escapes

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.5 Scripting

Comments

The ‘#’ character introduces an end-of-line comment. All characters until and including the end of line are ignored.

Displaying Arbitrary Text

The ‘echo’ (‘ec’) command prints its arguments to stdout.

Sourcing External Command Files

The command ‘source filename’ reads commands from the named file. Its minimal abbreviation is ‘so’.

Setting and Unsetting the Variables

The mail variables are set using ‘set’ (‘se’) command. The command takes a list of assignments. The syntax of an assignment is

name=string

Assign a string value to the variable. If string contains whitespace characters it must be enclosed in a pair of double-quote characters (‘"’)

name=number

Assign a numeric value to the variable.

name

Assign boolean True value.

noname

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.

Example: 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

Setting and Unsetting Shell Environment Variables

Shell environment may be modified using ‘setenv’ (‘sete’) command. The command takes a list of assignments. The syntax of an assignment is:

name=value

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.

name

Delete the variable name from the environment (“unset” it).

Conditional Statements

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:

s

True if mail is operating in mail sending mode.

r

True if mail is operating in mail reading mode.

t

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@farlep.net gray@mirddin.farlep.net
set

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.6 How to Alter the Behavior of mail

Following variables control the behavior of GNU mail:

append

Type: Boolean, Read-Only
Default: True

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.

appenddeadletter

Type: Boolean.
Default: False.

If this variable is True, the contents of canceled letter is appended to the user’s dead.letter file. Otherwise it overwrites its contents.

askbcc

Type: Boolean.
Default: False.

When set to True the user will be prompted to enter Bcc field before composing the message.

askcc

Type: Boolean.
Default: True.

When set to True the user will be prompted to enter Cc field before composing the message.

asksub

Type: Boolean.
Default: True in interactive mode, False otherwise.

When set to True the user will be prompted to enter Subject field before composing the message.

autoinc

Type: Boolean.
Default: True.

Automatically incorporate newly arrived messages.

autoprint

Type: Boolean.
Default: False.

Causes the delete command to behave like dp - thus, after deleting a message, the next one will be typed automatically.

bang

Type: Boolean.
Default: False.

When set, every occurrence of ! in arguments to ! command is replaced with the last executed command.

byname

Type: Boolean
Default: Unset

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. This variable overrides the ‘record’ variable.

It is set by the --byname (-F) command line option.

datefield

Type: Boolean.
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.

charset

Type: string
Default: ‘auto

The value of this variable controls the output character set for the header fields encoding using RFC 2047. If the variable is unset, no decoding is performed and the fields are printed as they are. If the variable is set to ‘auto’, mail tries to deduce the name of the character set from the value of LC_ALL environment variable. Otherwise, its value is taken as the name of the charset.

cmd

Type: String.
Default: Unset.

Contains default shell command for pipe.

columns

Type: Numeric.
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.

crt

Type: Boolean or Numeric
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.

debug

Type: String to boolean
Default: Not set

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.

decode-fallback

Type: String.
Default: ‘none’.

This variable controls the way to represent characters that cannot be rendered using current character set. It can have three values:

none

Such characters are not printed at all. The conversion process stops at the first character that cannot be rendered.

copy-pass

The characters are displayed ‘as is’. Notice, that depending on your setup, this may screw-up your terminal settings.

copy-octal

Unprintable characters are represented by their octal codes. Printable ones are printed ‘as is’.

debug

Type: Boolean
Default: Unset

This variable is not used. It exists for compatibility with other mailx implementations and for future use.

dot

Type: Boolean.
Default: False.

If True, causes mail to interpret a period alone on a line as the terminator of a message you are sending.

emptystart

Type: Boolean.
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.

editheaders

Type: Boolean.
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.

escape

Type: String.
Default: ~

If defined, the first character of this option gives the character to denoting escapes.

flipr

Type: Boolean
Default: Unset

If set, the variable flipr swaps the meanings of reply and Reply commands (see Replying).

folder

Type: String.
Default: Unset.

The name of the directory to use for storing folders of messages. If unset, $HOME is assumed.

fromfield

Type: Boolean.
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.

header

Type: Boolean.
Default: True, unless started with --nosum (-N) option.

Whether to run headers command automatically after entering interactive mode.

headline

Type: String
Default: ‘%>%a%4m %18f %16d %3l/%-5o %s

A format string to use for the header summary. The ‘%’ character introduces a format specifier. Valid format specifiers are:

LetterMeaning
%aMessage attributes.
%dThe date when the message was received.
%fThe address of the message sender.
%lThe number of lines of the message.
%mMessage number.
%oThe number of octets (bytes) in the message.
%sMessage subject (if any).
%SMessage subject (if any) in double quotes.
%>A ‘>’ for the current message, otherwise a space.
%<A ‘<’ for the current message, otherwise a space.
%%A ‘%’ character.

Some additional symbols are allowed between ‘%’ and the specifier letter. The ‘-’ character immediately following ‘%’ indicates that this field should be left aligned. Similarly, 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 values are aligned to the left.

A number following ‘%’ or the alignment flag, indicates the field width. Consider, for example, the following specifiers:

%m

Print current message number. Take as much screen columns as necessary to output it.

%4m
%+4m

Print current message number. Occupy 4 screen columns, truncate the output if it does not fit that width. Align the output to the right.

%-4m

Same as above, but align to the left.

hold

Type: Boolean.
Default: False.

When set to True, the read or saved messages will be stored in user’s mailbox ($HOME/mbox). Otherwise, they will be held in system mailbox also. This option is in effect only when operating upon user’s system mailbox.

ignore

Type: Boolean.
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.

ignoreeof

Type: Boolean.
Default: False.

Controls whether typing EOF character terminates the letter being composed.

indentprefix

Type: String.
Default: "\t" (a tab character).

String used by the ~m tilde escape for indenting quoted messages.

inplacealiases

Type: Boolean
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.

keep

Type: Boolean, 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.

keepsave

Type: Boolean.
Default: False.

Controls whether saved messages should be kept in system mailbox too. This variable is in effect only when operating upon a user’s system mailbox.

mailx

Type: Boolean.
Default: False.

When set, enables mailx compatibility mode. This mode has the following effects:

metamail

Type: Boolean or String.
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"
mimenoask

Type: String
Default: Empty

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

metoo

Type: Boolean.
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.

mode

Type: String, Read-Only
Default: The name of current operation mode.

This variable keeps the name of the current operation mode. Its possible values are:

headers

The program is started with the --headers (-H) command line option (see Invoking Mail).

exist

The program is started with the --exist (-e) command line option (see Invoking Mail).

print

The program is started with the --print (-p) command line option (see Invoking Mail).

read

The program operates in read mode. This is the default.

send

The program operates in send mode. This means it was given one or more recipient addresses in the command line.

nullbody

Type: Boolean
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'
showenvelope

Type: Boolean
Default: Unset

If this variable is set, the print command will include the STMP envelope in its output.

nullbodymsg

Type: String
Default: Null message body; hope that’s ok

Keeps the 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.

onehop

Type: Boolean
Default: Unset

This variable is not used. It exists for compatibility with other mailx implementations and for future use.

outfolder

Type: String.
Default: Unset.

Contains the directory in which files created by save, write, etc. commands will be stored. When unset, current directory is assumed.

page

Type: Boolean.
Default: False.

If set to True, the pipe command will emit a linefeed character after printing each message.

prompt

Type: String.
Default: "? "

Contains the command prompt sequence.

quiet

Type: Boolean
Default: Unset

This variable is not used. It exists for compatibility with other mailx implementations and for future use.

quit

Type: Boolean.
Default: False, unless started with --quit (-q) option.

When set, causes keyboard interrupts to terminate the program.

rc

Type: Boolean.
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.

readonly

Type: Boolean
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.

record

Type: String.
Default: Unset.

When set, any outgoing message will be saved to the named file.

recursivealiases

Type: Boolean
Default: True

When set, mail will expand aliases recursively.

regex

Type: Boolean.
Default: True.

Setting this to True enables use of regular expressions in ‘/.../’ message specifications.

replyprefix

Type: String
Default: ‘Re:

Sets the prefix that will be used when constructing the subject line of a reply message.

replyregex

Type: String
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 expression 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).

return-address

Type: String
Default: unset

Sets the return email address to use when sending messages. If unset, the address is composed from the current user name and the host name.

save

Type: Boolean.
Default: True.

When set, the aborted messages will be stored in the user’s dead.file. See also appenddeadletter.

screen

Type: Numeric.
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.

sendmail

Type: String.
Default: sendmail:/usr/lib/sendmail

Contains URL of the mail transport agent.

sendwait

Type: Boolean
Default: Unset

This variable is not used. It exists for compatibility with other mailx implementations and for future use.

showto

Type: Boolean
Default: False

If the message was sent by the user, print its recipient address in the header summary.

Sign

Type: String.
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.

sign

Type: String.
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.

showto

Type: Boolean
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.

subject

Type: String.
Default: Unset.

Contains default subject line. This will be used when asksub is off.

toplines

Type: Numeric.
Default: 5

Number of lines to be displayed by top and Top commands.

variable-strict
varstrict

Type: Boolean.
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.

See Setting and Unsetting the Variables.

variable-pretty-print
varpp

Type: Boolean.
Default: False.

If this variable is set, the listing output by set contains short descriptions before each variable. See Setting and Unsetting the Variables.

verbose

Type: Boolean.
Default: False.

When set, the actual delivery of messages is displayed on the user’s terminal.

xmailer

Type: Boolean.
Default: Set.

Controls whether the header ‘X-Mailer’ should be added to outgoing messages. The default value of this header is

X-Mailer: mail (GNU Mailutils 3.0)

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.5.7 Personal and System-wide Configuration Files

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.6 messages — Count the Number of Messages in a Mailbox

Messages 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:

StatementReference
debugSee debug statement.
tlsSee tls statement.
mailboxSee mailbox statement.
lockingSee locking statement.

In addition to the common mailutils options (see Common Options), the program accepts the following command line options:

-q
--quiet
-s
--silent

Be quiet. Display only number of messages per mailbox, without leading text.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.7 movemail — Moves Mail from the User Maildrop to the Local File

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: movemail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.7.1 Movemail Configuration

The following configuration file statements affect the behavior of movemail:

Movemail Config: preserve bool

If bool is ‘true’, do not remove messages from the source mailbox.

Movemail Config: reverse bool

If bool is ‘true’, reverse message sorting order.

Movemail Config: emacs bool

If bool is ‘true’, output information used by Emacs rmail interface.

Movemail Config: ignore-errors bool

Continue moving messages after errors. By default, mailfromd exits immediately if it cannot copy a message.

Movemail Config: program-id fmt

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):

progname

The program name.

source

URL of the source mailbox.

source_user

User part of the source mailbox URL.

source_host

Host part of the source mailbox URL.

source_path

Path part of the source mailbox URL.

dest

URL of the destination mailbox

dest_user

User part of the destination mailbox URL.

dest_host

Host part of the destination mailbox URL.

dest_path

Path 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}"
Movemail Config: uidl bool

Avoid copying the message if a message with the same UIDL already exists in the destination mailbox.

Movemail Config: verbose level

Set verbosity level.

Movemail Config: mailbox-ownership method-list

Define list of methods for setting ownership of the destination mailbox. The method-list argument can contain the following elements:

copy-id

Copy owner UID and GID from the source mailbox. This method works only with local mailboxes, i.e.: ‘mbox’ (UNIX mailbox), ‘maildir’ and ‘mh’.

copy-name

Get owner name from the source mailbox URL and obtain UID and GID for this user using mailutils authorization methods.

set-id=uid[:gid]

Set supplied uid and gid. If gid is not supplied, it is read from the /etc/passwd record for this UID.

set-name=user

Make destination mailbox owned by user.

Movemail Config: max-messages count

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.

Movemail Config: onerror actions

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

Abort the transfer and terminate the program. This is the default action.

skip

Skip to the next message.

delete

Delete the affected message.

count

Count this message as processed.

Each keyword can be prefixed with ‘no’ to reverse its meaning.

The following standard Mailutils statements are supported:

StatementReference
debugSee debug statement.
tlsSee tls statement.
mailboxSee mailbox statement.
lockingSee locking statement.
pamSee pam statement.
sqlSee sql statement.
virtdomainSee virtdomain statement.
radiusSee radius statement.
ldapSee ldap statement.
authSee auth statement.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: movemail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.7.2 Setting Destination Mailbox Ownership

Editor’s note:

The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: movemail   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.7.3 Movemail Usage Summary

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

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:

--emacs

Output information used by Emacs rmail interface.

--ignore-errors

Try to continue after errors.

--max-messages=count

Process at most count messages.

--notify

Enable biff notification.

--onerror=kw[,kw...]

What to do on errors. See onerror statement, for a description of kw.

-P modelist
--owner=modelist

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.

-p
--preserve
--keep-messages

Don’t remove transferred messages from the source mailbox.

--program-id=fmt

Set program identifier for diagnostics (default: the program name). See movemail-program-id, for a description of its argument.

-r
--reverse

Reverse the order of retrieved messages.

-u
--uidl

Use UIDLs to avoid downloading the same message twice.

-v
--verbose

Increase verbosity level.

The common options are also understood (see Common Options).

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.8 readmsg — Extract Messages from a Folder

The readmsg utility extracts messages from a mailbox according to the criteria specified in the command line. These criteria are:

  1. A lone ‘*’ means “select all messages in the mailbox”.
  2. A list of message numbers may be specified. Values of ‘0’ and ‘$’ in the list both mean the last message in the mailbox. For example:
    readmsg 1 3 0
    

    extracts three messages from the folder: the first, the third, and the last.

  3. Finally, the selection may be some text to match. This will select a mail message which exactly matches the specified text. For example,
    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. Normally only the first message which matches the pattern is printed.

Unless one of the informational options is used, at least one command line argument must be present. Informational options are: --help (-?), --usage, and --version (-V).

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: readmsg   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.8.1 Invocation of readmsg.

-a
--show-all

If a pattern is use for selection show all messages that match pattern by default only the first one is presented.

-d
--debug

Display mailbox debugging information.

-f mailbox
--folder=mailbox

Specified the default mailbox.

-h
--header

Show the entire header and ignore the weedlist.

-n
--no-header

Do not print the message header.

-p
--form-feed

Put form-feed (Control-L) between messages instead of newline.

-w weedlist
--weedlist=weedlist

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: readmsg   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.8.2 Configuration of readmsg.

Following configuration statements affect the behavior of readmsg:

Readmsg Conf: header bool

If bool is ‘true’, display entire headers.

Readmsg Conf: weedlist str

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

Readmsg Conf: no-header bool

If bool is ‘true’, exclude all headers.

Readmsg Conf: form-feeds bool

If bool is ‘true’, output formfeed character between messages.

Readmsg Conf: folder url

Set the URL of the mailbox folder to read.

Readmsg Conf: show-all-match bool

If bool is ‘true’, print all messages matching pattern, not only the first.

StatementReference
debugSee Debug Statement.
tlsSee TLS Statement.
mailboxSee Mailbox Statement.
lockingSee Locking Statement.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.9 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 provides two implementations of this language: a stand-alone sieve interpreter and a sieve translator and filter. The following sections describe these utilities in detail.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: sieve   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.9.1 A Sieve Interpreter

Sieve interpreter sieve allows to apply Sieve scripts to an 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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: sieve interpreter   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.9.1.1 Invoking sieve

The sieve invocation syntax is:

sieve [options] script

where script denotes the filename of the sieve program to parse, and options is one or more of the following:

-c
--compile-only

Compile script and exit.

--clear-library-path
--clearpath

Clear Sieve library path. See also clear-library-path.

--clear-include-path

Clear Sieve include path. See also clear-include-path.

-d[flags]
--debug[=flags]

Specify debug flags. The flags argument is a sequence of one or more of the following letters:

gEnable main parser traces
TEnable mailutils traces
PTrace network protocols
tEnable sieve trace
iTrace the program instructions
-D
--dump

Compile the script, dump disassembled code on standard output and exit.

-e address
--email address

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.

-I dir
--includedir=dir

Append directory dir to the list of directories searched for include files. See also include-path.

-f
--mbox-url=mbox

Mailbox to sieve (defaults to user’s system mailbox). See also mbox-url.

-k
--keep-going

Keep on going if execution fails on a message. See also keep-going.

-L dir
--libdir=dir

Append directory dir to the list of directories searched for library files. See also library-path.

--libdir-prefix=dir

Add dir to the beginning of the list of directories searched for library files.

-M url
--mailer=url

Define the URL of the default mailer.

-n
--no-actions
--dry-run

Dry run: do not execute any actions, just print what would be done.

--no-program-name

Do not prefix diagnostic messages with the program name.

-t ticket
--ticket=ticket

Ticket file for mailbox authentication. See also ticket.

-v
--verbose

Log all actions executed. See also verbose.

See also Common Options.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: sieve interpreter   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.9.1.2 Sieve Configuration

The behavior of sieve is affected by the following configuration statements:

StatementReference
debugSee debug statement.
tlsSee tls statement.
mailboxSee mailbox statement.
lockingSee locking statement.
loggingSee logging statement.
mailerSee mailer statement.

The following statements configure sieve-specific features:

Sieve Conf: sieve { ... }

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:

Sieve Conf: clear-library-path bool

If bool is ‘true’, clear library search path.

Sieve Conf: clear-include-path bool

If bool is ‘true’, clear include search path.

Sieve Conf: library-path path

Add directories to sieve library search path. Argument is a string containing a colon-separated list of directories.

Sieve Conf: library-path-prefix path

Add directories to the beginning if the library search path. Argument is a string containing a colon-separated list of directories.

Sieve Conf: include-path path

Add directories to the include search path. Argument is a string containing a colon-separated list of directories.

Sieve Conf: keep-going bool

If bool is ‘true’, do not abort if execution of a Sieve script fails on a particular message.

Sieve Conf: mbox-url url

Sets URL of the mailbox to be processed.

Sieve Conf: ticket file

Sets the name of the ticket file for user authentication.

Sieve Conf: debug flags

Sets Sieve debug flags. See Logging and Debugging, for a detailed description.

Sieve Conf: verbose bool

If bool is ‘true’, log all executed actions.

Sieve Conf: line-info bool

If bool is ‘true’, print source locations along with action logs. This statement takes effect only if verbose true is also set.

Sieve Conf: email addr

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: sieve interpreter   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.9.1.3 Logging and debugging

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:

t

This flag enables sieve tracing. It means that every test will be logged when executed.

T

This flag enables debugging of underlying mailutils library.

P

Trace network protocols: produces log of network transactions executed while running the script.

g

Enable main parser traces. This is useful for debugging the sieve grammar.

i

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: sieve interpreter   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.9.1.4 Extending sieve

The 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:

  1. Look up the name in a symbol table. If the name begins with ‘comparator-’ it is looked up in the comparator table. If it begins with ‘test-’, the test table is searched instead. Otherwise the name is looked up in the action table.
  2. If the name is found, the search is terminated.
  3. Otherwise, transform the name. First, any ‘comparator-’ or ‘test-’ prefix is stripped. Then, any character other than alphanumeric characters, ‘.’ and ‘,’ is replaced with dash (‘-’). The name thus obtained is used as a file name of an external loadable module.
  4. Try to load the module. The module is searched in the following search paths (in the order given):
    1. Mailutils module directory. By default it is $prefix/lib/mailutils.
    2. The value of the environment variable LTDL_LIBRARY_PATH.
    3. Additional search directories specified with the. --libdir-prefix command line option (see libdir-prefix), or the library-path-prefix configuration statement (see library-path-prefix).
    4. Additional search directories specified with the library-path statement (see library-path) in Sieve configuration file.
    5. Additional search directories specified with the. --libdir command line option (see libdir).
    6. Additional search directories specified with the #searchpath Sieve directive (see #searchpath).
    7. System library search path: The system dependent library search path (e.g. on Linux it is set by the contents of the file /etc/ld.so.conf and the value of the environment variable 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:

    1. the libtool archive extension ‘.la
    2. the extension used for native dynamic libraries on the host platform, e.g., ‘.so’, ‘.sl’, etc.
  5. If the module is found, sieve executes its initialization function (see below) and again looks up the name in the symbol table. If found, search terminates successfully.
  6. If either the module is not found, or the symbol wasn’t found after execution of the module initialization function, search is terminated with an error status. sieve then displays the following diagnostic message:
    source for the required action NAME is not available
    

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: sieve   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.9.2 A Sieve to Scheme Translator and Filter

Editor’s note:

The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised.

A Sieve to Scheme Translator sieve2scm translates a given Sieve script into an equivalent Scheme program and optionally executes it. The program itself is written in Scheme and requires presence of Guile version 1.8 or newer on the system. For more information on Guile refer to Overview in The Guile Reference Manual.

-f filename
--file filename

Set input file name.

-o filename
--output filename

Set output file name

-L dirname
--lib-dir dirname

Set sieve library directory name

-d level
--debug level

Set debugging level

The Scheme programs produced by sieve2scm can be used with guimb or maidag.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.10 guimb — A Mailbox Scanning and Processing Language

Guimb 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:

User function: guimb-message msg

Processes message msg. This function can alter the message using Guile primitives supplied by mailutils.

The following function definitions are optional:

User function: guimb-getopt args

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.

User function: guimb-end

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

GNU Mailutils Manual:   Section:   Chapter:     FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

Specifying Scheme Program to Execute

Specifying Scheme Program to Execute

The Scheme module that defines message processing functions is given via the following options:

-s module
--source module

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.

-f module
--file module

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:

-e expr
--expression expr

Evaluate scheme expression.

GNU Mailutils Manual:   Section:   Chapter:     FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

Specifying Mailboxes to Operate Upon

Specifying Mailboxes to Operate Upon

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 defmbox

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

GNU Mailutils Manual:   Section:   Chapter:     FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

Passing Options to Scheme

Passing Options to Scheme

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

GNU Mailutils Manual:   Section:   Chapter:     FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

Command Line Option Summary

Command Line Option Summary

This is a short summary of the command line options available to guimb.

-d
--debug

Start with debugging evaluator and backtraces.

-e expr
--expression expr

Execute given Scheme expression.

-L dir
--load-path dir

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.

-m path
--mail-spool=path

Set path to the mailspool directory

-f progfile
--file progfile

Read Scheme program from progfile.

-g arg
--guile-command arg

Append arg to the command line passed to Scheme program.

-{ ... -}

Pass all command line options enclosed between -{ and -} to Scheme program.

-m
--mailbox mbox

Set default mailbox name.

-u
--user name

Act as local MDA for user name.

-h
--help

Display help message.

-v
--version

Display program version.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.11 maidag

Editor’s note:

The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised.

The name ‘maidag’ stands for Mail delivery agent. It is a general-purpose MDA offering a rich set of features. It can operate both in traditional mode, reading the message from its standard input, and in LMTP mode. Maidag 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. Thus, maidag supersedes both mail.local and mail.remote utilities from GNU Mailutils versions prior to 2.0.

Maidag 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, maidag offers much more flexibility than other popular MDAs, such as procmail.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: maidag   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.11.1 Using maidag with Sendmail.

When used as a MDA with Sendmail, maidag must be invoked from the local mailer definition in the sendmail.cf file. It must have the following flags set: ‘lswS’. 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 flags ‘fn’ may be specified to allow maidag to generate the usual ‘From ’ envelope instead of the one supplied by sendmail.

If you wish to use maidag 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/maidag,
        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/maidag')
define(`LOCAL_MAILER_ARGS', `mail $u')

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: maidag   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.11.2 Using maidag with Exim.

Using maidag with Exim is quite straightforward. The following example illustrates the definition of the appropriate transport and director in exim.conf:

# transport
maidag_pipe:
  driver = pipe
  command = /usr/local/sbin/maidag $local_part
  return_path_add
  delivery_date_add
  envelope_to_add
  
# director
maidag:
  driver = localuser
  transport = maidag_pipe

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: maidag   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.11.3 Using maidag with MeTA1.

MeTA1 (http://meta1.org) communicates with the delivery agent using LMTP.

LMTP mode is enabled in maidag by the ‘lmtp yes’ statement. The socket to listen on must be specified using server statement (see Server Settings). For the purposes of this section, let’s suppose maidag will listen on a UNIX socket /var/spool/meta1/lmtpsock. Then, the following (minimal) maidag configuration will do the job:

# Start in LMTP mode.
lmtp yes;
# 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";

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: maidag   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.11.4 Mailbox Quotas

Mailbox quota is a limit on the size of the mailbox. When a mailbox size reaches this limit, maidag 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:

exit-quota-tempfail yes;

in which case a temporary error will be returned.

The mailbox quota can be retrieved from the following sources:

  1. Authentication method.
  2. DBM file.
  3. SQL database.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Mailbox Quotas   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.11.4.1 Keeping Quotas in DBM File

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 maidag --show-config-options, if not sure.

The quota database should have the following structure:

Key

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.

Value

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 valid quota database

# 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 quota-db configuration statement, e.g.:

quota-db /etc/mail/quota.db;

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Mailbox Quotas   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.11.4.2 Keeping Quotas in SQL Database

Configuration statement quota-query allows to specify a special query to retrieve the quota from the database. Currently (as of mailutils version 3.0) 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}'

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. Maidag always uses the first tuple from the set returned by mailbox quota query. So, you may 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 the quota for the user, which will be used by maidag. 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-query "SELECT quota "
            "FROM mailbox_quota "
            "WHERE user_name IN ('${user}','00DEFAULT') "
            "ORDER BY user_name DESC";

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: maidag   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.11.5 Maidag Scripting

Maidag 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.0, 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:

~
%h

Expands to the recipient home directory.

%u

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:

language "python"
script "~/.maidag-py-filter"

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Maidag Scripting   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.11.5.1 Sieve Maidag Filters

The file name of the Sieve filter to use is specified using ‘script’ configuration statement. For example, the following configuration statement:

script "~/.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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Maidag Scripting   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.11.5.2 Scheme Maidag Filters

The file name of the Scheme mail filter is specified using ‘script’ configuration statement. For example, the following configuration statement:

script "~/.maidag.scm"

instructs ‘maidag’ to use file ‘.maidag.scm’ in the recipient home directory as a Scheme filter.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Maidag Scripting   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.11.5.3 Python Maidag Filters

The file name of the Python mail filter is specified using ‘script’ configuration statement. For example, the following configuration statement:

script "~/.maidag.py"

instructs ‘maidag’ to use 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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: maidag   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.11.6 Forwarding

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.

Maidag provides a forwarding feature that is useful to compensate the lack of it.

Name of the forward file is given using forward-file configuration statement. A common usage is:

forward-file .forward;

The forward file is always searched in the recipient home directory.

Before actually using the 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 can be configured using forward-file-checks statement. Its argument is a list of the following keywords:

groupwritablefile
file_iwgrp

The file must not be group writable.

worldwritablefile
file_iwoth

The file must not be world writable.

linkedfileinwritabledir
link

The file cannot be a symlink in a writable directory.

fileingroupwritabledir
dir_iwgrp

The file cannot reside in a group writable directory.

fileinworldwritabledir
dir_iwoth

The file cannot reside in a world writable directory.

all

All of the above checks.

The default is ‘forward-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);

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: maidag   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.11.7 Delivering Messages to a URL.

When invoked with the --url command line option, maidag treats its arguments as a list of mailbox URLs and attempts to deliver the message to each of them.

For example:

$ maidag --url maildir:///home/smith/Mail

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: maidag   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.11.8 Remote Mailbox Delivery

Maidag can be used to deliver mail to remote mailboxes, such as ‘imap’ or ‘smtp’. If the mailbox URL is ‘smtp’ or ‘sendmail’, the message is actually forwarded over SMTP to the remote node, so maidag acts as a message transfer agent. For example:

$ maidag --url smtp://10.10.1.100:24

This command line will send the message to the machine ‘10.10.1.100’ using port ‘24’ (private mail system).

The ‘prog’ mailbox may be of special use. Delivering to this 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:

prog://program?args

Here, program is the absolute pathname of the program binary, and args are its arguments, separated by ‘&’ signs.

|program args

In this notation, args are command line arguments separated by white space.

In both cases, args do not include argv[0].

The ‘prog’ mailbox may be used, in particular, to implement mailing lists with MeTA1.

For example, suppose that the maidag 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 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 |
+---------------------+---------------------------------------+

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: maidag   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.11.9 Maidag Configuration File Summary

The behavior of maidag is affected by the following configuration statements:

StatementReference
debugSee debug statement.
mailboxSee mailbox statement.
lockingSee locking statement.
pamSee pam statement.
sqlSee sql statement.
virtdomainSee virtdomain statement.
radiusSee radius statement.
ldapSee ldap statement.
authSee auth statement.
mailerSee mailer statement.
serverSee Server Settings. Used only in LMTP mode.
aclSee acl statement.
tcp-wrappersSee tcp-wrappers statement.
Maidag Config: ex-multiple-delivery-success bool

In case of multiple delivery, exit with code 0 if at least one delivery has succeeded.

Maidag Config: ex-quota-tempfail bool

Indicate temporary failure if the recipient is over his mail quota. By default, permanent failure is returned. See Mailbox Quotas.

Maidag Config: quota-db file

Set the name of DBM quota database file. See DBM Quotas.

Maidag Config: sieve-filter pattern

Set file name or name pattern of the Sieve filter file. See Sieve Maidag Filters.

Maidag Config: message-id-header name

When logging Sieve actions, identify messages by the value of this header.

Maidag Config: guile-filter pattern

File name or name pattern for Guile filter file. See Scheme Maidag Filters.

Maidag Config: debug flags

Set additional debugging flags. Valid flags are:

g

Print guimb stack traces.

t

Enable sieve trace (MU_SIEVE_DEBUG_TRACE).

i

Enable sieve instructions trace (MU_SIEVE_DEBUG_INSTR).

l

Log executed Sieve actions.

Maidag Config: stderr bool

Log to stderr instead of syslog.

Maidag Config: forward-file file

Process forward file file. See Forwarding.

Maidag Config: forward-file-checks list

Configure safety checks for the forward file. See forward-file-checks.

Maidag Config: lmtp bool

Run in LMTP mode.

Maidag Config: group list

In LMTP mode, retain supplementary groups from list.

Maidag Config: listen url

In LMTP mode, listen on url. Valid URLs are: ‘tcp://host:port’ (note that port is mandatory), ‘file://socket-file-name’ or ‘socket://socket-file-name’.

Maidag Config: reuse-address bool

Reuse existing address (LMTP mode). Default is ‘yes’.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.12 mimeview

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/3, 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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mimeview   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.12.1 Mimeview Invocation

The following table summarizes options specific for mimeview:

-a[type-list]
--no-ask[=type-list]

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/*').

-d[flags]
--debug[=flags]

Enables debugging output. Flags is a sequence of characters specifying the desired debugging level. Following characters are meaningful in flags:

g

Enables debugging of mime.types parser

l

Enables debugging of mime.types lexical analyzer (warning: produces very copious output)

1

Prints basic information about actions to be executed and reports about exit status of executed commands.

2

Additionally displays each file name along with its MIME type

3

Additionally traces the process of looking up the matching entry in mailcap files.

digits from 4 to 9

The same as 3, currently.

If flags are not given, the default ‘9’ is assumed.

--metamail[=file]

Run metamail to display files, instead of using the internal mechanisms. If file is specified, it is taken as metamail command line.

-h
--no-interactive
--print

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.

-n
--dry-run

Do not do anything, just print what would be done. Implies --debug=1, unless the debugging level is set up explicitly.

-t file
--mimetypes file

Use file as mime.types file. If file is a directory, use file/mime.types

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mimeview   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.12.2 Mimeview Config

The following configuration statements affect the behavior of mimeview:

StatementReference
debugSee Debug Statement.
Mimeview Config: debug number

Set mimeview debug level. See –debug, for a description of debug levels.

Mimeview Config: mimetypes file

Read file instead of the default mime.types.

Mimeview Config: metamail program

Use program to display files.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.13 POP3 Daemon

The pop3d daemon implements the Post Office Protocol Version 3 server.

pop3d has two operation modes:

Inetd

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.

Standalone

The server runs as daemon, forking a child for each new connection.

The server operation mode is configured using mode statement (see mode).

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: pop3d   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.13.1 Login delay

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.0, 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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: pop3d   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.13.2 Auto-expire

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:

  1. Expired messages are deleted by 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.

  2. Expired messages remain in the mailbox after closing it. The system administrator is supposed to run a cron job that purges the mailboxes. Such a cron job can be easily implemented using 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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: pop3d   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.13.3 Bulletins

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 mbox

Set the URL of the bulletin source mailbox.

bulletin-db file

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: pop3d   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.13.4 Pop3d Configuration

The following configuration file statements affect the behavior of pop3d.

StatementReference
debugSee debug statement.
tlsSee tls statement.
mailboxSee mailbox statement.
lockingSee locking statement.
loggingSee logging statement.
pamSee pam statement.
sqlSee sql statement.
virtdomainSee virtdomain statement.
radiusSee radius statement.
ldapSee ldap statement.
authSee auth statement.
serverSee Server Settings.
aclSee acl statement.
tcp-wrappersSee tcp-wrappers statement.
Pop3d Conf: undelete bool

On startup, clear deletion marks from all the messages.

Pop3d Conf: expire n

Automatically expire read messages after n days. See Auto-expire, for a detailed description.

Pop3d Conf: delete-expired bool

Delete expired messages upon closing the mailbox. See Auto-expire, for a detailed description.

Pop3d Conf: tls-required bool

Always require STLS command before entering authentication phase.

Pop3d Conf: login-delay duration

Set the minimal allowed delay between two successive logins. See Login delay, for more information.

Pop3d Conf: stat-file file

Set the name of login statistics file for the login-delay facility. See Login delay, for more information.

Pop3d Conf: bulletin-source file

Get bulletins from the specified mailbox. See Bulletins, for a detailed description.

Pop3d Conf: bulletin-db file

Set bulletin database file name. See Bulletins, for a detailed description.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: pop3d   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.13.5 Command line options

The following table summarizes all pop3d command line options.

-d[number]
--daemon[=number]

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.

-i
--inetd

Run in inetd mode.

--foreground

Remain in foreground.

The Mailutils common options are also understood. See Common Options.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.14 IMAP4 Daemon

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 Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: imap4d   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.14.1 Namespace

GNU imap4d supports a notion of namespaces defined in RFC 2342. A namespace is a set of directories upon which the user has certain permissions. It should be understood that these permissions apply only if the underlying filesystem allows them.

The three namespaces supported by imap4d are:

Personal Namespace

A namespace that is within the personal scope of the authenticated user on a particular connection. The user has all permissions on this namespace.

Other Users’ Namespace

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.

Shared Namespace

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, imap4d starts with the following namespaces:

Personal Namespace

The home directory of the user, if exists.

Other Users’ Namespace

Empty

Shared Namespace

Empty

Note, that this means that by default, a user won’t be able to see or otherwise access mailboxes residing in the directories other than his own home.

To change these defaults, use shared-namespace and other-namespace configuration statements:

shared-namespace list

Set shared namespace.

other-namespace list

Set other users’ namespace.

For both statements, the argument is a list of directories that belong to this namespace, e.g.:

shared-namespace (/var/spool/mail,/var/mail);

If during the session the user creates a mailbox within either of these namespaces, the mode of the mailbox is determined by the following configuration statements:

shared-mailbox-mode mode

Set file mode for mailboxes created in shared namespace.

other-mailbox-mode mode

Set file mode for mailboxes created in other users’ namespace.

In both cases, the argument, mode is a list of symbolic mode settings, similar to that used by chmod. It is a list of comma-separated mode change commands. Each command 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:

shared-namespace-mode g=rw;

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: imap4d   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.14.2 Configuration of imap4d.

The behavior of imap4d is altered by the following configuration statements:

StatementReference
debugSee debug statement.
tlsSee tls statement.
mailboxSee mailbox statement.
lockingSee locking statement.
loggingSee logging statement.
pamSee pam statement.
sqlSee sql statement.
virtdomainSee virtdomain statement.
radiusSee radius statement.
ldapSee ldap statement.
authSee auth statement.
serverSee Server Settings.
aclSee acl statement.
tcp-wrappersSee tcp-wrappers statement.
Imap4d Conf: shared-namespace list

Set shared namespace. List is a list of strings. See Namespace, for a detailed description.

Imap4d Conf: other-namespace list

Set other users’ namespace. List is a list of strings. See Namespace, for a detailed description.

Imap4d Conf: shared-mailbox-mode str

Set file mode for mailboxes created within shared namespace. See Namespace, for a detailed description.

Imap4d Conf: other-mailbox-mode str

Set file mode for mailboxes created within other users’ namespace. See Namespace, for a detailed description.

Imap4d Conf: login-disabled bool

Disable LOGIN command, if bool is ‘true’.

Imap4d Conf: create-home-dir bool

Create nonexistent user home directories. See also home-dir-mode, below.

Imap4d Conf: home-dir-mode mode

Set file mode for created user home directories. Mode is specified in octal.

The default value for mode is ‘700’ (‘drwx------’ in ls terms).

Imap4d Conf: tls-required bool

Require successful STARTTLS command before entering authentication phase.

Imap4d Conf: preauth mode

Configure PREAUTH mode. Valid arguments are:

prog:///program-name

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.

ident[://:port]

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.

stdio

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.

Imap4d Conf: preauth-only bool

If bool is ‘true’, use only preauth mode. If unable to setup it, disconnect immediately.

Imap4d Conf: ident-keyfile file

Set DES keyfile for decoding encrypted ident responses. Used with ‘ident://’ preauth mode.

Imap4d Conf: ident-encrypt-only bool

Use only encrypted IDENT responses.

Imap4d Conf: id-fields list

Set list of fields to return in response to ID command.

Valid field names are:

name

Package name (‘GNU Mailutils’).

version

Package version (‘3.0’).

vendor

Vendor name (‘GNU’).

support-url

The string ‘http://www.gnu.org/software/mailutils

address

The string ‘51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA’.

os

OS name.

os-version

OS version number.

command

Name of the imap4d binary.

arguments

Invocation command line.

environment

List of environment variables with their values.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: imap4d   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.14.3 Starting imap4d

imap4d 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

Command Line Options

-d[number]
--daemon[=number]

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.

-i
--inetd

Run in inetd mode.

--foreground

Run in foreground.

--preauth

Start in preauth mode

--test

Run in test mode.

See also Common Options.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.15 Comsat Daemon

Comsatd is the server which receives reports of incoming mail and notifies users, wishing to get this service. It can be started either from inetd.conf or as a standalone daemon.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: comsatd   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.15.1 Starting comsatd

-d
--daemon

Run as a standalone daemon.

-i
--inetd

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.

-t
--test

Test mode. In this mode, comsatd takes two arguments: URL of a mailbox and QID of the message from that mailbox, e.g.:

$ comsatd --test /var/mail/root 34589
--foreground

Don’t detach from the controlling terminal, remain in foreground.

See also Common Options.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: comsatd   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.15.2 Configuring comsatd

Following configuration statements affect the behavior of comsatd:

StatementReference
debugSee debug statement.
loggingSee logging statement.
mailboxSee mailbox statement.
lockingSee locking statement.
aclSee acl statement.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Configuring comsatd   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.15.2.1 General Settings

These statements control the general behavior of the comsat daemon:

Comsatd Conf: max-lines number

Set maximum number of message body lines to be output.

Comsatd Conf: allow-biffrc bool

Enable or disable processing of user’s .biffrc file. By default, it is enabled.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Configuring comsatd   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.15.2.2 Security Settings

These statements control the way comsatd fights possible flooding attacks.

Comsatd Conf: max-requests number

Set maximum number of incoming requests per ‘request-control-interval’.

Comsatd Conf: request-control-interval duration

Set the request control interval.

Comsatd Conf: overflow-delay-time duration

Set initial amount of time to sleep, after the first overflow occurs.

Comsatd Conf: overflow-control-interval duration

Set overflow control interval. If two consecutive overflows happen within that interval, the overflow-delay-time is doubled.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: comsatd   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.15.3 A per-user Configuration File

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:

beep

Produce an audible signal.

echo [-n] string [string...]

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.

exec prog arglist

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:

$u

Expands to username

$h

Expands to hostname

$H{name}

Expands to value of message header ‘name’.

$B(c,l)

Expands to message body. c and l give maximum number of characters and lines in the expansion. When omitted, they default to 400, 5.

Example I

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

Example II

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"

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.16 MH — The MH Message Handling System

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mh   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.16.1 Major differences between Mailutils MH and other MH implementations

  1. UUCP addresses are not supported;
  2. Mailutils supports a set of new format specifications (see Format String Diffs);
  3. Mailutils provides a set of new profile variables (see Profile Variable Diffs);
  4. All programs recognize --help and --version options

    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.

  5. Several programs behave differently (see Program Diffs);

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Diffs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.16.1.1 New and Differing MH Format Specifications

MH Format: string decode (string str)

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.

MH Format: string package ()

Returns package name (string ‘mailutils’).

MH Format: string package_string ()

Returns full package string (e.g. ‘GNU Mailutils 2.1’)

MH Format: string version ()

Returns mailutils version.

MH Format: string unre (string str)

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%>
MH Format: void reply_regex (string r)

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.

MH Format: boolean isreply ([string str])

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.

MH Format: boolean rcpt (‘to’ | ‘cc’ | ‘me’ | ‘all’)

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.

MH Format: string concat ()

Appends whitespace + arg to string register.

MH Format: string printhdr (string str)

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.

MH Format: string in_reply_to ()

Generates the value for ‘In-reply-to:’ header according to RFC 2822.

MH Format: string references ()

Generates the value for ‘References:’ header according to RFC 2822.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Diffs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.16.1.2 New MH Profile Variables

Variable: MH Variable string Charset

Controls the character set in which the components decoded via the decode (see decode function) format function should be output.

Variable: MH Variable string Reply-Regex

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Diffs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.16.1.3 Differences in MH Program Behavior

anno

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

burst

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

comp

Understands -build option.

fmtdump

This command is not provided. Use fmtcheck instead.

inc
mhl

The ‘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’.

mhn
mhparam

The -all mode does not display commented out entries.

pick

New 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:

BUse basic regular expressions
EUse extended regular expressions
IIgnore case
CCase 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...
prompter
  1. Prompter attempts to use GNU Readline library, if it is installed. Consequently, arguments to -erase and -kill option must follow GNU style key sequence notation (see keyseq in GNU Readline Library).

    If prompter is built without readline, it accepts the following character notations:

    \nnnn

    Here, n stands for a single octal digit.

    ^chr

    This notation is translated to the ASCII code ‘chr + 0100’.

  2. Component continuation lines are not required to begin with a whitespace. If leading whitespace is not present, prompter will add it automatically.
refile
  1. Linking messages between folders goes against the logic of Mailutils, so refile never makes links even if called with -link option. The latter is actually a synonym for -copy, which preserves the original message.
  2. The -preserve option is not implemented. It is retained for backward compatibility only.
  3. Message specs and folder names may be interspersed.
repl

Understands -use option. Disposition shell provides use command.

rmm
  1. Different behaviour if one of the messages in the list does not exist:

    Mailutils rmm does not delete any messages. Standard rmm in this case deletes all messages preceding the non-existent one.

  2. The rmm utility will unlink messages, if the rmmproc profile component has empty value, e.g.:
    rmmproc:
    
sortm

New 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

List the ordered messages using a format string given by -form or -format option.

-dry-run

Do not actually sort messages, rather print what would have been done. This is useful for debugging purposes.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17 mailutils

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.1 Invocation Syntax

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:

2047

Decodes or encodes email message headers.

acl

Tests Mailutils access control lists.

cflags

Shows compiler options needed to compile with Mailutils.

dbm

Invokes a DBM management tool.

;filter

Applies a chain of filters to the input.

help

Displays a terse help summary.

imap

Invokes an IMAP4 client shell (in development).

info

Displays information about Mailutils compile-time configuration.

ldflags

Constructs a ld(1) command line for linking a program with Mailutils.

logger

Logs information using Mailutils log facility.

pop

Invokes a POP3 client shell.

query

Queries configuration values.

wicket

Scans wicket for matching URLs

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.2 mailutils help

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.3 mailutils info

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.4 mailutils cflags

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`

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.5 mailutils ldflags

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:

mbox

Link in the UNIX mbox format support.

mh

Link in the MH format support.

maildir

Link in the Maildir format support.

imap

Link in the IMAP protocol support.

pop

Link in the POP protocol support.

nntp

Link in the NNTP protocol support.

mailer

Enable support for mailers.

sieve

Link in the support for Sieve mail filtering language.

dbm

Link in the support for DBM databases (libmu_dbm library).

auth

Link in the Mailutils authentication library.

guile

Provide Guile language bindings.

python

Provide Python language bindings.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.6 mailutils query

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.7 mailutils 2047

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.8 mailutils filter

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.9 mailutils acl

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.10 mailutils wicket

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.11 mailutils dbm

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils dbm   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.11.1 Create a Database

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils dbm   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.11.2 Add Records to a Database

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils dbm   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.11.3 Delete Records

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils dbm   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.11.4 List the Database

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils dbm   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.11.5 Dump the Database

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils dbm   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.11.6 Dump Formats

As of version 3.0, 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:

#:version=1.0

Indicates that the data that follow are in version 1.0 format.

#:filename=s

Original database file name, without directory parts.

#:uid=n

Owner UID.

#:user=s

Owner name.

#:gid=n

Owner GID

#:group=s

Owner group name.

#:mode=o

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==

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils dbm   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.11.7 Dbm Exit Codes

The table below summarizes exit codes used by mailutils dbm:

CodeSymbolic nameMeaning
0EX_OKSuccessful termination
64EX_USAGECommand line usage error
65EX_DATAERRError 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.
66EX_NOINPUTCannot open input file
67EX_NOUSERNo such user or UID when trying to set output file ownership
69EX_UNAVAILABLEOperation cannot be performed due to some kind of problem (e.g. access to the file denied, etc.)
70EX_SOFTWAREInternal software error
74EX_IOERRInput/output error

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.12 mailutils logger

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

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.13 mailutils pop

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.

POP protocol commands

connect [-tls] hostname [port]

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

stls

Start TLS negotiation. This command is valid only after successful unencrypted connection has been initiated (using connect without -tls argument).

user name

Send user name to the server. The pass command must follow.

pass [password]

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.

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

capa [-reread] [name...]

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.

noop

Send a ‘NOOP’ (no operation) command to the server.

stat

Get the mailbox size and number of messages in it.

uidl [number]

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.

list [number]

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.

retr number

Retrieve a message.

top msgno [number]

Display message headers and first number (default 5) of lines of its body.

dele number

Mark message for deletion.

rset

Remove deletion marks.

quit

Quit pop3 session.

disconnect

Close existing connection.

Internal commands

verbose [on|off|mask|unmask] [secure [payload]]

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.

prompt string

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:

VariableExpansion
userLogin name of the authenticated POP3 user. If the session is not authenticated yet, expands to ‘[nouser]’.
hostName of the remote host, or ‘[nohost]’ if no connection is established.
program-nameName of the program, as typed on the command line to invoke it.
canonical-program-namemailutils
packageMailutils
versionMailutils version number (3.0)
statusSession 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

Exit the program.

help [command]
? [command]

Without arguments displays a list of commands with possible arguments and short descriptions.

With one argument, displays a terse description for the given command.

history

Shows command history.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.14 mailutils imap

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.

IMAP protocol commands

Most commands in this group correspond (with minor differences) to IMAP commands described in RFC 35014.

imap command: connect [-tls] host [port]

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

imap command: capability [-reread] [name...]

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.

imap command: starttls

Starts TLS negotiation. This command is valid only after unencrypted connection has been successfully initiated using connect without the -tls option.

imap command: login user [password]

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.

imap command: logout
imap command: quit

Quits the imap session.

imap command: id [-test kw] [arg...]

Sends IMAP ID command. See RFC 29715, 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.

imap command: check

Requests a server checkpoint.

imap command: select [mbox]

Selects the named mailbox. Without argument, selects ‘INBOX’.

imap command: examine [mbox]

Examines the named mailbox, i.e. selects it in read-only mode. If mbox is not given, ‘INBOX’ is assumed.

imap command: status mbox kw [kw...]

Gets mailbox status. Valid keywords (kw arguments) are: ‘MESSAGES’, ‘RECENT’, ‘UIDNEXT’, ‘UIDVALIDITY’, and ‘UNSEEN’. Keywords are case-insensitive.

imap command: fetch msgset items

Fetches message data. See RFC 3501, section 6.4.56, for a discussion of its arguments.

imap command: store msgset items

Alters mailbox data. See RFC 3501, section 6.4.67, for a discussion of its arguments.

imap command: close

Closes the currently selected mailbox (with expunge).

imap command: unselect

Closes the currently selected mailbox (without expunge).

imap command: delete mbox

Deletes the mailbox mbox.

imap command: rename old-name new-name

Renames existing mailbox old-name to new-name.

imap command: expunge

Permanently removes messages marked for deletion.

imap command: create name

Creates new mailbox with the given name.

imap command: append [-time datetime] [-flag flag] mailbox file

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
imap command: list ref mbox

Lists matching mailboxes. See RFC 3501, section 6.3.88, for a discussion of its arguments.

imap command: lsub ref mbox

Lists subscribed mailboxes (RFC 3501, section 6.3.99).

imap command: subscribe mbox

Subscribes to a mailbox.

imap command: unsubscribe mbox

Removes mailbox mbox from the subscription list.

imap command: noop

Sends a no operation command.

imap command: disconnect

Closes existing connection.

Internal commands

The imap shell implements the same set of internal commands as pop shell: See Internal commands. There is only one imap-specific internal command:

imap command: uid [on|off]

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.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.15 mailutils send

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:

-F address
--from=address

Supplies envelope sender address.

-T address
--rcpt=address

Supplies envelope recipient address. It can be specified multiple times.

-t
--read-recipients

Instructs the program to read recipient email addresses from the message ‘To:’, ‘Cc:’, and ‘Bcc:’ headers.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: mailutils   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.17.16 mailutils smtp

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

Initializing connection

smtp command: connect [-tls] host [port]

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.

Connection parameters

A number of parameters is associated with an open connection:

domain

Domain name used in EHLO statement. Defaults to the current host name.

The following parameters are used for ESMTP authentication:

username

User name.

password

User password.

service

GSASL service name.

realm

Realm name.

host

Host name.

url

SMTP URL. It can contain all of the above. Default is smtp://

These parameters are manipulated using the following statements:

smtp command: set param value [param value...]

Sets parameter param to value. Several parameters can be set with one set statement.

smtp command: clear [param...]

Unset the supplied connection parameters. If used without arguments, unsets all parameters.

smtp command: list [param...]

Lists the values of the connection parameters. If used without arguments, lists all parameters.

SMTP commands

smtp command: ehlo [domain]

Sends the ESMTP greeting. Unless domain is supplied, the connection parameter ‘domain’ is used.

smtp command: capa [name...]

Lists the server capabilities.

smtp command: starttls

Initiates encrypted connection. This command is disabled if the connection is opened with the -tls option.

smtp command: auth mech [mech...]

Authenticate using the supplied mechanisms.

smtp command: rset

Reset the session state.

smtp command: from [email]

Sets sender email address. If used without arguments, prints the sender email address.

smtp command: to [email]

Sets recipient email address. If used without arguments, prints all recepient names collected so far.

smtp command: smtp command [args...]

Sends the command with its arguments verbatim.

smtp command: quit

Quits the SMTP session.

smtp command: send [file]

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

Internal commands are the same as in pop shell: See Internal commands.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Programs   Up: Top   FastForward: Sieve Language   Contents: Table of ContentsIndex: Function Index

4 Mailutils Libraries

Editor’s note:

This node is to be written.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Libraries   Up: Top   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5 Sieve Language

The input language understood by the GNU Sieve Library is a superset of the Sieve language as described in RFC 3028.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Sieve Language   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.1 Lexical Structure

Whitespace and Comments

Comments are semantically equivalent to whitespace and can be used anyplace that whitespace is (with one exception in multi-line strings, as described below).

There are two kinds of comments: hash comments, that begin with a ‘#’ character that is not contained within a string and continue until the next newline, and C-style or bracketed comments, that are delimited by ‘/*’ and ‘*/’ tokens. The bracketed comments may span multiple lines. E.g.:

if size :over 100K
  { # this is a comment
    discard;
  }
  
if size :over 100K
  { /* this is a comment
       this is still a comment */ discard /* this is a comment again
     */ ;
  }

Like in C, bracketed comments do not nest.

Lexical Tokens

The basic lexical entities are identifiers and literals.

An identifier is a sequence of letters, digits and underscores, that begins with a letter or underscore. For example, header and check_822_again are valid identifiers, whereas 1st is not. A special form of identifier is tag: it is an identifier prefixed with a colon (‘:’), e.g.: :comparator.

A literal is a data that is not executed, merely evaluated “as is”, to be used as arguments to commands. There are four kinds of literals:

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Sieve Language   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.2 Syntax

Being designed for the sole purpose of filtering mail, Sieve has a very simple syntax.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Syntax   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.2.1 Commands

The basic syntax element is a command. It is defined as follows:

command-name [tags] args

where command-name is an identifier representing the name of the command, tags is an optional list of optional or tagged arguments and args is a list of required or positional arguments.

Positional arguments are literals delimited with whitespace. They provide the command with the information necessary to its proper functioning. Each command has a fixed number of positional arguments. It is an error to supply more arguments to the command or to give it fewer arguments than it accepts.

Optional arguments allow to modify the behaviour of the command, like command line options in UNIX do. They are a list of tags (see Lexical Structure) separated by whitespace. An optional argument may have at most one parameter.

Each command understands a set of optional arguments. Supplying it tags that it does not understand results in an error.

For example, consider the following command

header :mime :comparator "i;octet" ["to", "from"] "bug-mailutils@gnu.org"

Here, given that header takes two positional arguments: header is command name, the list ["to", "from"] is first positional argument and the string "bug-mailutils@gnu.org" is second positional argument. There are two optional arguments: :mime and :comparator. The latter has a string "i;octet" as its parameter.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Syntax   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.2.2 Actions Described

An action is a Sieve command that performs some operation over a message. Actions do the main job in any Sieve program. Syntactically, an action is a command terminated with semicolon, e.g.:

keep;

fileinto "mbox";

GNU Sieve provides the full set of actions described in RFC 3028. It also allows to extend this set using loadable actions. See Actions, for detailed discussion of actions.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Syntax   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.2.3 Control Flow

The only control flow statement Sieve has is if statement. In its simplest form it is:

if condition { … }

The effect of this statement is that the sequence of actions between the curly braces is executed only if the condition evaluates to true.

A more elaborate form of this statement allows to execute two different sets of actions depending on whether the condition is true or not:

if condition { … } else { … }

The most advanced form of the “if” statement allows to select an action depending on what condition from the set of conditions is met.

if cond1 { … } elsif cond2 { … } else { … }

There may be any number of “elsif” branches in an “if” statement. However it may have at most one “else” branch. Notes for C programmers:

  1. The braces surrounding each branch of an “if” statement are required.
  2. The “else if” construct is disallowed. Use “elsif” keyword instead.

Here’s an example of “if” statement:

if header :contains "from" "coyote"
  {
    discard;
  }
elsif header :contains ["subject"] ["$$$"]
  {
    discard;
  }
else
  {
    fileinto "INBOX";
  }

The following section describes in detail conditions used in “if” statements.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Syntax   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.2.4 Tests and Conditions

Tests are Sieve commands that return boolean value. E.g. the test

header :contains "from" "coyote"

returns true only if the header “From” of the current message contains substring “coyote”.

The tests shipped with the GNU Sieve are described in Tests.

Condition is a Sieve expression that evaluates to true or false. In its simplest form, condition is just a Sieve test.

To reverse the sense of a condition use keyword not, e.g.:

not header :contains "from" "coyote"

The results of several conditions may be joined together by logical and and or operations. The special form allof takes several tests as its arguments and computes the logical and of their results. Similarly, the form anyof performs logical or over the results of its arguments. E.g.:

if anyof (not exists ["From", "Date"],
          header :contains "from" "fool@example.edu")
  {
    discard;
  }

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Sieve Language   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.3 Preprocessor

Preprocessor statements are a GNU extension to the Sieve language. The syntax for a preprocessor statement is similar to that used in C programming language, i.e. a pound character (‘#’) followed by a preprocessor directive and its arguments. Any amount of whitespace can be inserted between the ‘#’ and the directive. Currently implemented directives are include and searchpath.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Preprocessor   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.3.1 Sieve #include directive

The #include directive reads in the contents of the given file. The contents is “inserted” into the text being parsed starting at the line where the directive appears. The directive takes two forms:

#include "filename"

The filename is taken relative to the current directory.

#include <filename>"

The filename is searched in the list of include directories as specified by the -I command line options.

If filename starts with a directory separator character (‘/’) both forms have the same effect.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Preprocessor   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.3.2 Sieve #searchpath directive

The #searchpath directive adds its argument to the list of directories searched for loadable modules. It has the same effect as library-path Sieve configuration statement (see library-path).

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Sieve Language   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.4 Require Statement

Syntax:   require string;
          require string-list;

The require statement informs the parser that a script makes use of a certain extension. Multiple capabilities can be declared using the second form of the statement. The actual handling of a capability name depends on its suffix.

If the name starts with ‘comparator-’, it is understood as a request to use the specified comparator. The comparator name consists of the characters following the suffix.

If the name starts with ‘test-’, it means a request to use the given test. The test name consists of the characters following the suffix.

Otherwise, the capability is understood as a name of an action to be used.

The require statement, if present, must be used before any other statement that is using the required capability. As an extension, the GNU sieve allows the require and any other statements to be interspersed.

By default the following actions and comparators need not be explicitly required:

Example:

require ["fileinto", "reject"];

require "fileinto";

require "comparator-i;ascii-numeric";

When processing arguments for require statement, GNU libmu_sieve uses the following algorithm:

  1. Look up the name in a symbol table. If the name begins with ‘comparator-’ it is looked up in the comparator table. If it begins with ‘test-’, the test table is used instead. Otherwise the name is looked up in the action table.
  2. If the name is found, the search is terminated.
  3. Otherwise, transform the name. First, any ‘comparator-’ or ‘test-’ prefix is stripped. Then, any character other than alphanumeric characters, ‘.’ and ‘,’ is replaced with dash (‘-’). The name thus obtained is used as a file name of an external loadable module.
  4. Try to load the module. The module is searched in the following search paths (in the order given):
    1. Mailutils module directory. By default it is $prefix/lib/mailutils.
    2. Sieve library path as given with the -L options in the command line
    3. Additional search directories specified with the #searchpath directive.
    4. The value of the environment variable LTDL_LIBRARY_PATH.
    5. System library search path: The system dependent library search path (e.g. on Linux it is set by the contents of the file /etc/ld.so.conf and the value of the environment variable 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, libmu_sieve first attempts to find and load the given filename. If this fails, it tries to append the following suffixes to the file name:

    1. the libtool archive extension ‘.la
    2. the extension used for native dynamic libraries on the host platform, e.g., ‘.so’, ‘.sl’, etc.
  5. If the module is found, libmu_sieve executes its initialization function (see below) and again looks up the name in the symbol table. If found, search terminates successfully.
  6. If either the module is not found, or the symbol wasn’t found after execution of the module initialization function, search is terminated with an error status. libmu_sieve then issues the following diagnostic message:
    source for the required action NAME is not available
    

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Sieve Language   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.5 Comparators

GNU libmu_sieve supports the following built-in comparators:

i;octet

This comparator simply compares the two arguments octet by octet

i;ascii-casemap

It treats uppercase and lowercase characters in the ASCII subset of UTF-8 as the same. This is the default comparator.

i;ascii-numeric

Treats the two arguments as ASCII representation of decimal numbers and compares their numeric values. This comparator must be explicitly required prior to use.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Sieve Language   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.6 Tests

This section describes the built-in tests supported by GNU libmu_sieve. In the discussion below the following macro-notations are used:

match-type

This tag specifies the matching type to be used with the test. It can be one of the following:

:is

The :is match type describes an absolute match; if the contents of the first string are absolutely the same as the contents of the second string, they match. Only the string “frobnitzm” is the string “frobnitzm”. The null key “:is” and only “:is” the null value. This is the default match-type.

:contains

The :contains match type describes a substring match. If the value argument contains the key argument as a substring, the match is true. For instance, the string “frobnitzm” contains “frob” and “nit”, but not “fbm”. The null key “” is contained in all values.

:matches

The :matches version specifies a wildcard match using the characters ‘*’ and ‘?’. ‘*’ matches zero or more characters, and ‘?’ matches a single character. ‘?’ and ‘*’ may be escaped as ‘\\?’ and ‘\\*’ in strings to match against themselves. The first backslash escapes the second backslash; together, they escape the ‘*’.

:regex

The :regex version specifies a match using POSIX Extended Regular Expressions.

:value relation

The :value match type does a relational comparison between strings. Valid values for relation are:

"eq"

Equal

"ne"

Not Equal

"gt"

Greater Than

"ge"

Greater than or Equal

"lt"

Less Than

"le"

Less than or Equal

:count relation

This match type first determines the number of the specified entities (headers, addresses, etc.) in the message and does a relational comparison of the number of entities to the values specified in the test expression. The test expression must be a list of one element.

comparator

A comparator syntax item is defined as follows:

:comparator "comparator-name"

It instructs sieve to use the given comparator with the test. If comparator-name is not one of ‘i;octet’, ‘i;ascii-casemap’ it must be required prior to using it. For example:

require "comparator-i;ascii-numeric";

if header :comparator "i;ascii-numeric" :is "X-Num" "10"
  {
    ...
address-part

This syntax item is used when testing structured Internet addresses. It specifies which part of an address must be used in comparisons. Exactly one of the following tags may be used:

:all

Use the whole address. This is the default.

:localpart

Use local part of the address.

:domain

Use domain part of the address.

Notice, that match-type modifiers interact with comparators. Some comparators are not suitable for matching with :contains or :matches. If this occurs, sieve issues an appropriate error message. For example, the statement:

if header :matches :comparator "i;ascii-numeric"

would result in the following error message:

comparator `i;ascii-numeric' is incompatible with match type `:matches'
in call to `header'

GNU Sieve supports two kinds of tests. Built-in tests are defined within the library and do not require any external files. External tests are loadable modules that can be linked in at run time using the require statement (see Require Statement).

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Tests   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.6.1 Built-in Tests

Test: false

This test always evaluates to “false”.

Test: true

This test always evaluates to “true”.

Test: address [address-part] [comparator] [match-type] header-names key-list

Tagged arguments:

address-part

Selects the address part to compare. Default is the whole email address (:all).

comparator

Specifies the comparator to be used instead of the default i;ascii-casemap.

match-type

Specifies the match type to be used instead of the default :is.

Required arguments:

header-names

A list of header names.

key-list

A list of address values.

The address test matches Internet addresses in structured headers that contain addresses. It returns true if any header contains any key in the specified part of the address, as modified by comparator and match-type optional arguments.

This test returns true if any combination of the header-names and key-list arguments match.

The address primitive never acts on the phrase part of an email address, nor on comments within that address. Use the header test instead. It also never acts on group names, although it does act on the addresses within the group construct.

Example:

if address :is :all "from" "tim@example.com"
  {
     discard;
  } 
Test: size [:over | :under] limit(number)

The size test deals with the size of a message. The required argument limit represents the size of the message in bytes. It may be suffixed with the following quantifiers:

k
K

The number is expressed in kilobytes.

m
M

The number is expressed in megabytes.

g
G

The number is expressed in gigabytes.

If the tagged argument is ‘:over’, and the size of the message is greater than number, the test is true; otherwise, it is false.

If the argument is ‘:under’, and the size of the message is less than the number, the test is true; otherwise, it is false.

Otherwise, the test is true only if the size of the message equals exactly number. This is a GNU extension.

The size of a message is defined to be the number of octets from the initial header until the last character in the message body.

Test: envelope [address-part] [comparator] [match-type] envelope-part(string-list) key-list(string-list)

Tagged arguments:

address-part

Selects the address part to compare. Default is the whole email address (:all).

comparator

Specifies the comparator to be used instead of the default i;ascii-casemap.

match-type

Specifies the match type to be used instead of the default :is.

Required arguments:

envelope-parts

A list of envelope parts to operate upon.

key-list

A list of address values.

The envelope test is true if the specified part of the SMTP envelope matches the specified key.

If the envelope-part strings is (case insensitive) ‘from’, then matching occurs against the FROM address used in the SMTP MAIL command.

Notice, that due to the limitations imposed by SMTP envelope structure the use of any other values in envelope-parts header is meaningless.

Test: exists header-names(string-list)

Required arguments:

header-names

List of message header names.


The exists test is true if the headers listed in header-names argument exist within the message. All of the headers must exist or the test is false.

The following example throws out mail that doesn’t have a From header and a Date header:

if not exists ["From","Date"]
  {
     discard;
  }
Test: header [comparator] [match-type] [:mime] header-names(string-list) key-list(string-list)

Tagged arguments:

comparator

Specifies the comparator to be used instead of the default i;ascii-casemap.

match-type

Specifies the match type to be used instead of the default :is.

:mime

This tag instructs header to search through the mime headers in multipart messages as well.


Required arguments:

header-names

A list of header names.

key-list

A list of header values.


The header test evaluates to true if any header name matches any key. The type of match is specified by the optional match argument, which defaults to ":is" if not explicitly given.

The test returns true if any combination of the header-names and key-list arguments match.

If a header listed in header-names exists, it contains the null key (‘""’). However, if the named header is not present, it does not contain the null key. So if a message contained the header

X-Caffeine: C8H10N4O2

these tests on that header evaluate as follows:

header :is ["X-Caffeine"] [""] ⇒ false
header :contains ["X-Caffeine"] [""] ⇒ true

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Tests   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.6.2 External Tests

Test: numaddr [:over | :under] header-names(string-list) count(number)

Synopsis:

require "test-numaddr";
…
if numaddr args
  {
    …
  }

Description: This test is provided as an example of loadable extension tests. You must use ‘require "test-numaddr"’ statement before actually using it.

The numaddr test counts Internet addresses in structured headers that contain addresses. It returns true if the total number of addresses satisfies the requested relation.

If the tagged argument is ‘:over’ and the number of addresses is greater than count, the test is true; otherwise, it is false.

If the tagged argument is ‘:under’ and the number of addresses is less than count, the test is true; otherwise, it is false.

If the tagged argument is not given, ‘:over’ is assumed.

Test: pipe [:envelope] [:header] [:body] [:exit code(number)] [:signal code(number)] command(string)

Synopsis:

require "test-pipe";

if pipe command
  {
    …
  }

Description: The pipe test executes a shell command specified by its argument and pipes the entire message (including envelope) to its standard input. When given, tags :envelope, :header, and :body control what parts of the message to pipe to the command.

In the absence of the :exit tag, the test returns true if the command exits with code 0. If :exit is given, the test returns true if the command exits with code equal to its argument.

The :signal tag determines the result of the test in case if the program exits on signal. By default, the test returns false. If :signal is given and the number of signal which caused the program to terminate matches its argument, the test returns true.

Test: spamd [:host tcp-host(string)] [:port tcp-port(number)] [:socket unix-socket(string)] [:user name(string)] [:over | :under limit(string)]

Synopsis:

require "test-spamd";
…
if spamd args
  {
    # This is spam
    …
  }

Description: This test is an interface to SpamAssassin filter. It connects to the spamd daemon using connection parameters specified by tagged arguments :host and :port (if the daemon is listening on an INET socket), or :socket (if the daemon is listening on a UNIX socket) and returns true, if SpamAssassin qualifies the message as spam. Tagged argument limit alters the default behavior. Its value is a string representation of a floating point number. If the tag :over is used, then the test returns true if the spam score returned from SpamAssassin is greater than limit. Otherwise, if :under is used, the test returns true if the spam score is less than limit. The comparison takes into account three decimal digits.

Tagged argument :user allows to select a specific user profile. If it is not given, the user name is determined using the effective UID.

Before returning, the spamd test adds the following headers to the message:

X-Spamd-Status

YES’ or ‘NO’, depending on whether the message is qualified as spam or ham.

X-Spamd-Score

Actual spam score value.

X-Spamd-Threshold

Spam score threshold, as configured in SpamAssassin settings.

X-Spamd-Keywords

Comma-separated list of keywords, describing the spam checks that succeeded for this message.

Example:

request "test-spamd";

if spamd :host 127.0.0.1 :port 3333
  {
     discard;
  }
Test: list [comparator] [match-type] [ :delim delimiters(string) ] headers(string-list) keys(string-list)

Synopsis:

require "test-list";
if list args
  {
     … 
  }

Description: The list test evaluates to true if any of headers matches any key from keys. Each header is regarded as containing a list of keywords. By default, comma is assumed as list separator. This can be overridden by specifying the :delim tag, whose value is a string consisting of valid list delimiter characters.

Example:

This test can be used in conjunction with the spamd test described above:

require ["fileinto", "test-spamd", "test-list"];

if spamd :host 127.0.0.1 :port 3333
  {
     if list :matches :delim " ,"
             "X-Spamd-Keywords" [ "HTML_*", "FORGED_*" ]
       {      
          fileinto "~/mail/spam";
       }
     else
       {
          discard;
       }
  }
Test: timestamp [:before | :after] header(string) date(string)

Synopsis:

require "test-timestamp";

if timestamp arg
  {
     …
  }

Description: The timestamp test compares the value of a structured date header field (header) with the given date (date).

If the tagged argument is :after and the date from the header is after the specified date the result is true, otherwise, if the header date is before the given date, the result is false.

If the tagged argument is :before and the date from the header is before the specified date the result is true, otherwise, if the header date is after the given date, the result is false.

If no tagged argument is supplied, :after is assumed.

Almost any date format is understood. See Date Input Formats, for a detailed information on date formats.

Example:

The test below succeeds if the date in ‘X-Expire-Timestamp’ header is more than 5 days older than the current date:

require "test-timestamp";

if timestamp :before "X-Expire-Timestamp" "now - 5 days"
  {
     discard;
  }

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Sieve Language   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.7 Actions

There are two groups of GNU Sieve actions: built-in actions, which are defined within the library, and external actions, i.e. loadable modules that can be linked in at run time using the require statement (see Require Statement).

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Actions   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.7.1 Built-in Actions

The GNU libmu_sieve supports the following built-in actions:

Among them the first three actions do not need to be explicitly required by a require statement, while the others do.

These actions are described in detail below.

Action: stop

The stop action ends all processing. If no actions have been executed, then the keep action is taken.

Action: keep

The effect of this action is to preserve the current message in the mailbox. This action is executed if no other action has been executed.

Action: discard

Discard silently throws away the current message. No notification is returned to the sender, the message is deleted from the mailbox.

Example:

if header :contains ["from"] ["idiot@example.edu"]
  {
    discard;
  }
Action: fileinto [:permissions mode] folder

Required arguments:

folder

A string representing the folder name

Tagged arguments:

:permissions mode

Specifies the permissions to use, if the mailbox is created.

The fileinto action delivers the message into the specified folder. If the folder is local, it is created using permissions ‘0600’, for regular files, and ‘0700’ for directories. This default can be changed by using the :permissions tag. Its argument is a mode specification, similar to that used by chmod shell utility. It is a list of permissions settings separated by commas. Each setting begins with one of the following letters:

g

Set permissions for the users in the file group.

o

Set permissions for users not in the file’s group.

This letter must be followed by either ‘+’ or ‘=’ and the list of permissions to be set. This latter list is a string containing any one or both of the following characters:

r

Grant permission to read.

w

Grant permission to write.

For example, the following instruction creates the mailbox ~/shared which will be world readable and writable for the group:

  fileinto :permissions "g=rw,o=r" "~/shared"

Notice that:

  1. The :permissions setting are affected by the current umask value.
  2. Only r and w permissions can be set, since other permissions do not seem to be useful for mailboxes. However, for mailboxes that have a directory structure (such as maildir and MH), any settings in ‘g’ and ‘o’ sets imply setting the executable bit.
  3. Owner’s permissions cannot be set. The owner always has all permissions on the mailbox he created.
  4. The :permissions settings apply only to local mailboxes. They are ignored for remote mailboxes.
Action: reject reason

The optional reject action refuses delivery of a message by sending back a message delivery notification to the sender. It resends the message to the sender, wrapping it in a “reject” form, noting that it was rejected by the recipient. The required argument reason is a string specifying the reason for rejecting the message.

Example:

If the message contained

Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST)
From: coyote@desert.example.org
To: roadrunner@acme.example.com
Subject: I have a present for you

I've got some great birdseed over here at my place.
Want to buy it?

and the user’s script contained:

if header :contains "from" "coyote@desert.example.org"
  {
    reject "I am not taking mail from you, and I don't want
            your birdseed, either!";
  }

then the original sender <coyote@desert.example.org> would receive the following notification:

To: <coyote@desert.example.org>
X-Authentication-Warning: roadrunner set sender using -f flag
Content-Type: multipart/mixed; boundary=----- =_aaaaaaaaaa0
MIME-Version: 1.0
----- =_aaaaaaaaaa0
The original message was received at
Tue, 1 Apr 1997 09:07:15 -0800 from
coyote@desert.example.org.
Message was refused by recipient's mail filtering program.
Reason given was as follows:

I am not taking mail from you, and I don't want your
birdseed, either!

----- =_aaaaaaaaaa0
Content-Type: message/delivery-status

Reporting-UA: sieve; GNU Mailutils 0.1.3
Arrival-Date: Tue, 1 Apr 1997 09:07:15 -0800
Final-Recipient: RFC822; roadrunner@acme.example.com
Action: deleted
Disposition: automatic-action/MDN-sent-automatically;deleted
Last-Attempt-Date: Tue, 1 Apr 1997 09:07:15 -0800

----- =_aaaaaaaaaa0
Content-Type: message/rfc822

From: coyote@desert.example.org
To: roadrunner@acme.example.com
Subject: I have a present for you

I've got some great birdseed over here at my place.
Want to buy it?
----- =_aaaaaaaaaa0

If the reason argument is rather long, the common approach is to use the combination of the text: and #include keywords, e.g.:

if header :mime :matches "Content-Type"
          [ "*application/msword;*", "*audio/x-midi*" ]
  {
    reject text:
#include "nomsword.txt"
    .
    ;
  }
Action: redirect address

The redirect action is used to send the message to another user at a supplied address, as a mail forwarding feature does. This action makes no changes to the message body or existing headers, but it may add new headers. It also modifies the envelope recipient.

The redirect command performs an MTA-style “forward” — that is, what you get from a .forward file using sendmail under UNIX. The address on the SMTP envelope is replaced with the one on the redirect command and the message is sent back out. Notice, that it differs from the MUA-style forward, which creates a new message with a different sender and message ID, wrapping the old message in a new one.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Actions   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.7.2 External Actions

GNU Mailutils is shipped with a set of external Sieve actions. These actions are compiled as loadable modules and must be required prior to use (see Require Statement).

Action: moderator [:keep] [:address address(string)] [:source sieve-file(string)] [:program sieve-text(string)]

Synopsis:

require "moderator"
moderator args;

Description: This action is a moderator robot for Mailman-driven mail archives. A Mailman moderation request is a MIME message consisting of the following three parts:

NContent-TypeDescription
1text/plainIntroduction for the human reader.
2message/rfc822Original submission.
3message/rfc822Mailman control message.

Replying to part 3 (keeping the subject intact) instructs Mailman to discard the original submission.

Replying to part 3 while adding an ‘Approved:’ header with the list password in it approves the submission.

The moderator action spawns an inferior Sieve machine and filters the original submission (part 2) through it. If the inferior machine marks the message as deleted, the action replies to the control message, thereby causing the submission to be discarded. The ‘From:’ address of the reply can be modified using :address tag. After discarding the message, moderator marks it as deleted, unless it is given :keep tag.

If the :source tag is given, its argument specifies a Sieve source file to be used on the message. Otherwise, if :program is given, its argument supplies a Sieve program to be used on this message. At most one of these tags may be specified. Supplying them both, or supplying several instances of the same tag, is an error. The behavior of the action in this case is undefined.

If neither :program nor :source is given, moderator will create a copy of the existing Sieve machine and use it on the message.

The action checks the message structure: it will bail out if the message does not have exactly 3 MIME parts, or if parts 2 and 3 are not of ‘message/rfc822’ type. It is the responsibility of the caller to make sure the message is actually a valid Mailman moderation request (see the example below).


Example:

if allof(header :is "Sender" "mailman-bounces@gnu.org",
         header :is "X-List-Administrivia" "yes")
  {
     moderator :source "~/.sieve/mailman.sv";
  }
Action: pipe [:envelope] [:header] [:body] command(string)

Synopsis:

require "pipe";

pipe command

Description: The pipe action executes a shell command specified by its argument and pipes the entire message (including envelope) to its standard input. When given, tags :envelope, :header, and :body control what parts of the message to pipe to the command.


Example: The example below uses the maidag utility (see maidag) to forward the message to user ‘gray’ on the machine ‘mail.gnu.org’.

require "pipe";

pipe "/usr/sbin/maidag --url smtp://gray@mail.gnu.org"
Action: vacation [:days ndays(number)] [:subject subject(string)] [:aliases addrlist(string-list)] [:noreply noreply-address(string-list)] [:reply_regex expr(string)] [:reply_prefix prefix(string)] [:sender email(string)] [:database path(string)] [:return_address email(string)] [:header headers(string-list)] [:mime] [:always_reply] [:rfc2822] [:file] text(string)

Syntax:

require "vacation";
vacation args;

Description: The vacation action returns a message with text to the sender. It is intended to inform the sender that the recipient is not currently reading his mail.

If the :file tag is present, text is treated as the name of the file to read the body of the reply message from. When used together with tag :rfc2822, the file should be formatted as a valid RFC 2822 message, i.e. headers followed by empty line and body. Headers may not contain ‘To’, ‘From’, and ‘Subject’, as these will be generated automatically.

If the :subject tag is given, its argument sets the subject of the message. Otherwise, the subject is formed by prefixing original subject with ‘Re:’, or the prefix given with the :reply_prefix tag. Before prefixing, any original prefixes matching extended regular expression expr (:reply_regex tag) are stripped from the subject line. If :reply_regex is not specified, the default regexp is ‘^re: *’.

Another headers can be added using the :header tag. Its argument is a list of header strings, each one having the form ‘"name:value"’. Additional whitespace is allowed on both sides of the colon.

The :aliases tag instructs vacation to handle messages for any address in addrlist in the same manner as those received for the user’s principal email.

Before processing, vacation compares the sender address with its address exclusion list. Elements of this list are extended case-insensitive regular expressions. If the sender address matches any of these expressions, the message will not be replied. The default exclusion list is:

    .*-REQUEST@.*
    .*-RELAY@.*
    .*-OWNER@.*
    ^OWNER-.*
    ^postmaster@.*
    ^UUCP@.*
    ^MAILER@.*
    ^MAILER-DAEMON@.*

New entries can be added to this list using :noreply tag.

The :days tag sets the reply interval. A reply is sent to each sender once in ndays days. GNU Sieve keeps track of sender addresses and dates in file .vacation stored in the user’s home directory. The file name can be changed using the :database tag.

The tag :always_reply instructs vacation to respond to the message regardless of whether the user email is listed as a recipient for the message.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Sieve Language   FastForward: Reporting Bugs   Contents: Table of ContentsIndex: Function Index

5.8 GNU Extensions

This section summarizes the GNU extensions to the sieve language

  1. Multiline strings syntax

    GNU libmu_sieve understands the following multiline string syntax:

    text:[-][delimiter]
    ....
    delimiter
    

    The meaning of optional flags is the same as in shell “here document” construct: the dash strips all leading tab characters from the string body, thus allowing it to be indented in a natural fashion; delimiter introduces the new end-of-text delimiter instead of the default dot. If delimiter starts with a backslash, no preprocessing will be performed within a string.

  2. Handling of the require statement.
  3. header test

    The header takes an optional argument :mime, meaning to scan the headers from each part of a multipart message.

  4. size test

    The size test allows to omit the optional argument (:over|:under). In this case exact equality is assumed.

  5. envelope test

    The only value that can be meaningfully used as the first required argument of an envelope test is ‘from’. This limitation may disappear from the subsequent releases.

  6. fileinto action

    The fileinto action allows to specify permissions on the mailbox, in case it will be created (see fileinto).

  7. Match type optional argument.

    Along with the usual :is, :matches and :contains matching type, GNU sieve library understands :regex type. This matching type toggles POSIX Extended Regular Expression matching.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Sieve Language   Up: Top   FastForward: News   Contents: Table of ContentsIndex: Function Index

6 Reporting Bugs

Email bug reports to bug-mailutils@gnu.org.

As the purpose of bug reporting is to improve software, please be sure to include maximum information when reporting a bug. The information needed is:

The archives of bug-mailutils mailing list are available from http://mail.gnu.org/mailman/listinfo/bug-mailutils.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Reporting Bugs   Up: Top   FastForward: Acknowledgement   Contents: Table of ContentsIndex: Function Index

7 Getting News About GNU Mailutils

The two places to look for any news regarding GNU Mailutils are the Mailutils homepage at http://mailutils.org or http://www.gnu.org/software/mailutils, and the project page at http://savannah.gnu.org/projects/mailutils.

The updated versions of this manual are available online from http://mailutils.org/manual. See also Mailutils Wiki for the latest updates.

GNU Mailutils Manual:   Section:   Chapter:FastBack: News   Up: Top   FastForward: References   Contents: Table of ContentsIndex: Function Index

8 Acknowledgement

In no particular order,

GNU Mailutils Manual:   Section:   Chapter:FastBack: Acknowledgement   Up: Top   FastForward: Date Input Formats   Contents: Table of ContentsIndex: Function Index

Appendix A References

Editor’s note:

This node is to be written.

GNU Mailutils Manual:   Section:   Chapter:FastBack: References   Up: Top   FastForward: Usage Vars   Contents: Table of ContentsIndex: Function Index

Appendix B Date Input Formats

First, a quote:

Our units of temporal measurement, from seconds on up to months, are so complicated, asymmetrical and disjunctive so as to make coherent mental reckoning in time all but impossible. Indeed, had some tyrannical god contrived to enslave our minds to time, to make it all but impossible for us to escape subjection to sodden routines and unpleasant surprises, he could hardly have done better than handing down our present system. It is like a set of trapezoidal building blocks, with no vertical or horizontal surfaces, like a language in which the simplest thought demands ornate constructions, useless particles and lengthy circumlocutions. Unlike the more successful patterns of language and science, which enable us to face experience boldly or at least level-headedly, our system of temporal calculation silently and persistently encourages our terror of time.

… It is as though architects had to measure length in feet, width in meters and height in ells; as though basic instruction manuals demanded a knowledge of five different languages. It is no wonder then that we often look into our own immediate past or future, last Tuesday or a week from Sunday, with feelings of helpless confusion. …

— Robert Grudin, Time and the Art of Living.

This section describes the textual date representations that GNU programs accept. These are the strings you, as a user, can supply as arguments to the various programs. The C interface (via the get_date function) is not described here.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Date Input Formats   Up: Date Input Formats   FastForward: Usage Vars   Contents: Table of ContentsIndex: Function Index

B.1 General date syntax

A date is a string, possibly empty, containing many items separated by whitespace. The whitespace may be omitted when no ambiguity arises. The empty string means the beginning of today (i.e., midnight). Order of the items is immaterial. A date string may contain many flavors of items:

We describe each of these item types in turn, below.

A few ordinal numbers may be written out in words in some contexts. This is most useful for specifying day of the week items or relative items (see below). Among the most commonly used ordinal numbers, the word ‘last’ stands for -1, ‘this’ stands for 0, and ‘first’ and ‘next’ both stand for 1. Because the word ‘second’ stands for the unit of time there is no way to write the ordinal number 2, but for convenience ‘third’ stands for 3, ‘fourth’ for 4, ‘fifth’ for 5, ‘sixth’ for 6, ‘seventh’ for 7, ‘eighth’ for 8, ‘ninth’ for 9, ‘tenth’ for 10, ‘eleventh’ for 11 and ‘twelfth’ for 12.

When a month is written this way, it is still considered to be written numerically, instead of being “spelled in full”; this changes the allowed strings.

In the current implementation, only English is supported for words and abbreviations like ‘AM’, ‘DST’, ‘EST’, ‘first’, ‘January’, ‘Sunday’, ‘tomorrow’, and ‘year’.

The output of the date command is not always acceptable as a date string, not only because of the language problem, but also because there is no standard meaning for time zone items like ‘IST’. When using date to generate a date string intended to be parsed later, specify a date format that is independent of language and that does not use time zone items other than ‘UTC’ and ‘Z’. Here are some ways to do this:

$ LC_ALL=C TZ=UTC0 date
Mon Mar  1 00:21:42 UTC 2004
$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
2004-03-01 00:21:42Z
$ date --iso-8601=ns | tr T ' '  # --iso-8601 is a GNU extension.
2004-02-29 16:21:42,692722128-0800
$ date --rfc-2822  # a GNU extension
Sun, 29 Feb 2004 16:21:42 -0800
$ date +'%Y-%m-%d %H:%M:%S %z'  # %z is a GNU extension.
2004-02-29 16:21:42 -0800
$ date +'@%s.%N'  # %s and %N are GNU extensions.
@1078100502.692722128

Alphabetic case is completely ignored in dates. Comments may be introduced between round parentheses, as long as included parentheses are properly nested. Hyphens not followed by a digit are currently ignored. Leading zeros on numbers are ignored.

Invalid dates like ‘2005-02-29’ or times like ‘24:00’ are rejected. In the typical case of a host that does not support leap seconds, a time like ‘23:59:60’ is rejected even if it corresponds to a valid leap second.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Date Input Formats   Up: Date Input Formats   FastForward: Usage Vars   Contents: Table of ContentsIndex: Function Index

B.2 Calendar date items

A calendar date item specifies a day of the year. It is specified differently, depending on whether the month is specified numerically or literally. All these strings specify the same calendar date:

1972-09-24     # ISO 8601.
72-9-24        # Assume 19xx for 69 through 99,
               # 20xx for 00 through 68.
72-09-24       # Leading zeros are ignored.
9/24/72        # Common U.S. writing.
24 September 1972
24 Sept 72     # September has a special abbreviation.
24 Sep 72      # Three-letter abbreviations always allowed.
Sep 24, 1972
24-sep-72
24sep72

The year can also be omitted. In this case, the last specified year is used, or the current year if none. For example:

9/24
sep 24

Here are the rules.

For numeric months, the ISO 8601 format ‘year-month-day’ is allowed, where year is any positive number, month is a number between 01 and 12, and day is a number between 01 and 31. A leading zero must be present if a number is less than ten. If year is 68 or smaller, then 2000 is added to it; otherwise, if year is less than 100, then 1900 is added to it. The construct ‘month/day/year’, popular in the United States, is accepted. Also ‘month/day’, omitting the year.

Literal months may be spelled out in full: ‘January’, ‘February’, ‘March’, ‘April’, ‘May’, ‘June’, ‘July’, ‘August’, ‘September’, ‘October’, ‘November’ or ‘December’. Literal months may be abbreviated to their first three letters, possibly followed by an abbreviating dot. It is also permitted to write ‘Sept’ instead of ‘September’.

When months are written literally, the calendar date may be given as any of the following:

day month year
day month
month day year
day-month-year

Or, omitting the year:

month day

GNU Mailutils Manual:   Section:   Chapter:FastBack: Date Input Formats   Up: Date Input Formats   FastForward: Usage Vars   Contents: Table of ContentsIndex: Function Index

B.3 Time of day items

A time of day item in date strings specifies the time on a given day. Here are some examples, all of which represent the same time:

20:02:00.000000
20:02
8:02pm
20:02-0500      # In EST (U.S.  Eastern Standard Time).

More generally, the time of day may be given as ‘hour:minute:second’, where hour is a number between 0 and 23, minute is a number between 0 and 59, and second is a number between 0 and 59 possibly followed by ‘.’ or ‘,’ and a fraction containing one or more digits. Alternatively, ‘:second’ can be omitted, in which case it is taken to be zero. On the rare hosts that support leap seconds, second may be 60.

If the time is followed by ‘am’ or ‘pm’ (or ‘a.m.’ or ‘p.m.’), hour is restricted to run from 1 to 12, and ‘:minute’ may be omitted (taken to be zero). ‘am’ indicates the first half of the day, ‘pm’ indicates the second half of the day. In this notation, 12 is the predecessor of 1: midnight is ‘12am’ while noon is ‘12pm’. (This is the zero-oriented interpretation of ‘12am’ and ‘12pm’, as opposed to the old tradition derived from Latin which uses ‘12m’ for noon and ‘12pm’ for midnight.)

The time may alternatively be followed by a time zone correction, expressed as ‘shhmm’, where s is ‘+’ or ‘-’, hh is a number of zone hours and mm is a number of zone minutes. The zone minutes term, mm, may be omitted, in which case the one- or two-digit correction is interpreted as a number of hours. You can also separate hh from mm with a colon. When a time zone correction is given this way, it forces interpretation of the time relative to Coordinated Universal Time (UTC), overriding any previous specification for the time zone or the local time zone. For example, ‘+0530’ and ‘+05:30’ both stand for the time zone 5.5 hours ahead of UTC (e.g., India). This is the best way to specify a time zone correction by fractional parts of an hour. The maximum zone correction is 24 hours.

Either ‘am’/‘pm’ or a time zone correction may be specified, but not both.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Date Input Formats   Up: Date Input Formats   FastForward: Usage Vars   Contents: Table of ContentsIndex: Function Index

B.4 Time zone items

A time zone item specifies an international time zone, indicated by a small set of letters, e.g., ‘UTC’ or ‘Z’ for Coordinated Universal Time. Any included periods are ignored. By following a non-daylight-saving time zone by the string ‘DST’ in a separate word (that is, separated by some white space), the corresponding daylight saving time zone may be specified. Alternatively, a non-daylight-saving time zone can be followed by a time zone correction, to add the two values. This is normally done only for ‘UTC’; for example, ‘UTC+05:30’ is equivalent to ‘+05:30’.

Time zone items other than ‘UTC’ and ‘Z’ are obsolescent and are not recommended, because they are ambiguous; for example, ‘EST’ has a different meaning in Australia than in the United States. Instead, it’s better to use unambiguous numeric time zone corrections like ‘-0500’, as described in the previous section.

If neither a time zone item nor a time zone correction is supplied, time stamps are interpreted using the rules of the default time zone (see Specifying time zone rules).

GNU Mailutils Manual:   Section:   Chapter:FastBack: Date Input Formats   Up: Date Input Formats   FastForward: Usage Vars   Contents: Table of ContentsIndex: Function Index

B.5 Day of week items

The explicit mention of a day of the week will forward the date (only if necessary) to reach that day of the week in the future.

Days of the week may be spelled out in full: ‘Sunday’, ‘Monday’, ‘Tuesday’, ‘Wednesday’, ‘Thursday’, ‘Friday’ or ‘Saturday’. Days may be abbreviated to their first three letters, optionally followed by a period. The special abbreviations ‘Tues’ for ‘Tuesday’, ‘Wednes’ for ‘Wednesday’ and ‘Thur’ or ‘Thurs’ for ‘Thursday’ are also allowed.

A number may precede a day of the week item to move forward supplementary weeks. It is best used in expression like ‘third monday’. In this context, ‘last day’ or ‘next day’ is also acceptable; they move one week before or after the day that day by itself would represent.

A comma following a day of the week item is ignored.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Date Input Formats   Up: Date Input Formats   FastForward: Usage Vars   Contents: Table of ContentsIndex: Function Index

B.6 Relative items in date strings

Relative items adjust a date (or the current date if none) forward or backward. The effects of relative items accumulate. Here are some examples:

1 year
1 year ago
3 years
2 days

The unit of time displacement may be selected by the string ‘year’ or ‘month’ for moving by whole years or months. These are fuzzy units, as years and months are not all of equal duration. More precise units are ‘fortnight’ which is worth 14 days, ‘week’ worth 7 days, ‘day’ worth 24 hours, ‘hour’ worth 60 minutes, ‘minute’ or ‘min’ worth 60 seconds, and ‘second’ or ‘sec’ worth one second. An ‘s’ suffix on these units is accepted and ignored.

The unit of time may be preceded by a multiplier, given as an optionally signed number. Unsigned numbers are taken as positively signed. No number at all implies 1 for a multiplier. Following a relative item by the string ‘ago’ is equivalent to preceding the unit by a multiplier with value -1.

The string ‘tomorrow’ is worth one day in the future (equivalent to ‘day’), the string ‘yesterday’ is worth one day in the past (equivalent to ‘day ago’).

The strings ‘now’ or ‘today’ are relative items corresponding to zero-valued time displacement, these strings come from the fact a zero-valued time displacement represents the current time when not otherwise changed by previous items. They may be used to stress other items, like in ‘12:00 today’. The string ‘this’ also has the meaning of a zero-valued time displacement, but is preferred in date strings like ‘this thursday’.

When a relative item causes the resulting date to cross a boundary where the clocks were adjusted, typically for daylight saving time, the resulting date and time are adjusted accordingly.

The fuzz in units can cause problems with relative items. For example, ‘2003-07-31 -1 month’ might evaluate to 2003-07-01, because 2003-06-31 is an invalid date. To determine the previous month more reliably, you can ask for the month before the 15th of the current month. For example:

$ date -R
Thu, 31 Jul 2003 13:02:39 -0700
$ date --date='-1 month' +'Last month was %B?'
Last month was July?
$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
Last month was June!

Also, take care when manipulating dates around clock changes such as daylight saving leaps. In a few cases these have added or subtracted as much as 24 hours from the clock, so it is often wise to adopt universal time by setting the TZ environment variable to ‘UTC0’ before embarking on calendrical calculations.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Date Input Formats   Up: Date Input Formats   FastForward: Usage Vars   Contents: Table of ContentsIndex: Function Index

B.7 Pure numbers in date strings

The precise interpretation of a pure decimal number depends on the context in the date string.

If the decimal number is of the form yyyymmdd and no other calendar date item (see Calendar date items) appears before it in the date string, then yyyy is read as the year, mm as the month number and dd as the day of the month, for the specified calendar date.

If the decimal number is of the form hhmm and no other time of day item appears before it in the date string, then hh is read as the hour of the day and mm as the minute of the hour, for the specified time of day. mm can also be omitted.

If both a calendar date and a time of day appear to the left of a number in the date string, but no relative item, then the number overrides the year.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Date Input Formats   Up: Date Input Formats   FastForward: Usage Vars   Contents: Table of ContentsIndex: Function Index

B.8 Seconds since the Epoch

If you precede a number with ‘@’, it represents an internal time stamp as a count of seconds. The number can contain an internal decimal point (either ‘.’ or ‘,’); any excess precision not supported by the internal representation is truncated toward minus infinity. Such a number cannot be combined with any other date item, as it specifies a complete time stamp.

Internally, computer times are represented as a count of seconds since an epoch—a well-defined point of time. On GNU and POSIX systems, the epoch is 1970-01-01 00:00:00 UTC, so ‘@0’ represents this time, ‘@1’ represents 1970-01-01 00:00:01 UTC, and so forth. GNU and most other POSIX-compliant systems support such times as an extension to POSIX, using negative counts, so that ‘@-1’ represents 1969-12-31 23:59:59 UTC.

Traditional Unix systems count seconds with 32-bit two’s-complement integers and can represent times from 1901-12-13 20:45:52 through 2038-01-19 03:14:07 UTC. More modern systems use 64-bit counts of seconds with nanosecond subcounts, and can represent all the times in the known lifetime of the universe to a resolution of 1 nanosecond.

On most hosts, these counts ignore the presence of leap seconds. For example, on most hosts ‘@915148799’ represents 1998-12-31 23:59:59 UTC, ‘@915148800’ represents 1999-01-01 00:00:00 UTC, and there is no way to represent the intervening leap second 1998-12-31 23:59:60 UTC.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Date Input Formats   Up: Date Input Formats   FastForward: Usage Vars   Contents: Table of ContentsIndex: Function Index

B.9 Specifying time zone rules

Normally, dates are interpreted using the rules of the current time zone, which in turn are specified by the TZ environment variable, or by a system default if TZ is not set. To specify a different set of default time zone rules that apply just to one date, start the date with a string of the form ‘TZ="rule"’. The two quote characters (‘"’) must be present in the date, and any quotes or backslashes within rule must be escaped by a backslash.

For example, with the GNU date command you can answer the question “What time is it in New York when a Paris clock shows 6:30am on October 31, 2004?” by using a date beginning with ‘TZ="Europe/Paris"’ as shown in the following shell transcript:

$ export TZ="America/New_York"
$ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
Sun Oct 31 01:30:00 EDT 2004

In this example, the --date operand begins with its own TZ setting, so the rest of that operand is processed according to ‘Europe/Paris’ rules, treating the string ‘2004-10-31 06:30’ as if it were in Paris. However, since the output of the date command is processed according to the overall time zone rules, it uses New York time. (Paris was normally six hours ahead of New York in 2004, but this example refers to a brief Halloween period when the gap was five hours.)

A TZ value is a rule that typically names a location in the tz’ database. A recent catalog of location names appears in the TWiki Date and Time Gateway. A few non-GNU hosts require a colon before a location name in a TZ setting, e.g., ‘TZ=":America/New_York"’.

The ‘tz’ database includes a wide variety of locations ranging from ‘Arctic/Longyearbyen’ to ‘Antarctica/South_Pole’, but if you are at sea and have your own private time zone, or if you are using a non-GNU host that does not support the ‘tz’ database, you may need to use a POSIX rule instead. Simple POSIX rules like ‘UTC0’ specify a time zone without daylight saving time; other rules can specify simple daylight saving regimes. See Specifying the Time Zone with TZ in The GNU C Library.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Date Input Formats   Up: Date Input Formats   FastForward: Usage Vars   Contents: Table of ContentsIndex: Function Index

B.10 Authors of get_date

get_date was originally implemented by Steven M. Bellovin (smb@research.att.com) while at the University of North Carolina at Chapel Hill. The code was later tweaked by a couple of people on Usenet, then completely overhauled by Rich $alz (rsalz@bbn.com) and Jim Berets (jberets@bbn.com) in August, 1990. Various revisions for the GNU system were made by David MacKenzie, Jim Meyering, Paul Eggert and others.

This chapter was originally produced by François Pinard (pinard@iro.umontreal.ca) from the getdate.y source code, and then edited by K. Berry (kb@cs.umb.edu).

GNU Mailutils Manual:   Section:   Chapter:FastBack: Date Input Formats   Up: Top   FastForward: GNU FDL   Contents: Table of ContentsIndex: Function Index

Appendix C Configuring Help Summary

Running prog --help displays the short usage summary for prog utility (see Common Options). This summary is organized by groups of semantically close options. The options within each group are printed in the following order: a short option, eventually followed by a list of corresponding long option names, followed by a short description of the option. For example, here is an excerpt from the actual sieve --help output:

  -c, --compile-only         Compile script and exit
  -d, --debug[=FLAGS]        Debug flags
  -e, --email=ADDRESS        Override user email address

The exact visual representation of the help output is configurable via ARGP_HELP_FMT environment variable. The value of this variable is a comma-separated list of format variable assignments. There are two kinds of format variables. An offset variable keeps the offset of some part of help output text from the leftmost column on the screen. A boolean variable is a flag that toggles some output feature on or off. Depending on the type of the corresponding variable, there are two kinds of assignments:

Offset assignment

The assignment to an offset variable has the following syntax:

variable=value

where variable is the variable name, and value is a numeric value to be assigned to the variable.

Boolean assignment

To assign true value to a variable, simply put this variable name. To assign false value, prefix the variable name with ‘no-’. For example:

# Assign true value:
dup-args
# Assign false value:
no-dup-args

Following variables are declared:

Help Output: boolean dup-args

If true, arguments for an option are shown with both short and long options, even when a given option has both forms, for example:

  -e ADDRESS, --email=ADDRESS        Override user email address

If false, then if an option has both short and long forms, the argument is only shown with the long one, for example:

  -e, --email=ADDRESS        Override user email address

and a message indicating that the argument is applicable to both forms is printed below the options. This message can be disabled using dup-args-note (see below).

The default is false.

Help Output: boolean dup-args-note

If this variable is true, which is the default, the following notice is displayed at the end of the help output:

Mandatory or optional arguments to long options are also mandatory or optional for any corresponding short options.

Setting no-dup-args-note inhibits this message. Normally, only one of variables dup-args or dup-args-note should be set.

Help Output: offset short-opt-col

Column in which short options start. Default is 2.

$ sieve --help|grep ADDRESS
  -e, --email=ADDRESS        Override user email address
$ ARGP_HELP_FMT=short-opt-col=6 sieve --help|grep ARCHIVE
      -e, --email=ADDRESS        Override user email address
Help Output: offset long-opt-col

Column in which long options start. Default is 6. For example:

$ sieve --help|grep ADDRESS
  -e, --email=ADDRESS        Override user email address
$ ARGP_HELP_FMT=long-opt-col=16 sieve --help|grep ADDRESS
  -e,           --email=ADDRESS        Override user email address
Help Output: offset doc-opt-col

Column in which doc options start. A doc option isn’t actually an option, but rather an arbitrary piece of documentation that is displayed in much the same manner as the options. For example, in the output of folder --help:

Usage: folder [OPTION...] [action] [msg]
GNU MH folder
  Actions are:
      --list                 List the contents of the folder stack
  ...

the string ‘Actions are:’ is a doc option. Thus, if you set ARGP_HELP_FMT=doc-opt-col=6 the above part of the help output will look as follows:

Usage: folder [OPTION...] [action] [msg]
GNU MH folder
      Actions are:
      --list                 List the contents of the folder stack
  ...
Help Output: offset opt-doc-col

Column in which option description starts. Default is 29.

$ sieve --help|grep ADDRESS
  -e, --email=ADDRESS        Override user email address
$ ARGP_HELP_FMT=opt-doc-col=19 sieve --help|grep ADDRESS
  -e, --email=ADDRESS   Override user email address
$ ARGP_HELP_FMT=opt-doc-col=9 sieve --help|grep -i ADDRESS
  -e, --email=ADDRESS
         Override user email address

Notice, that the description starts on a separate line if opt-doc-col value is too small.

Help Output: offset header-col

Column in which group headers are printed. A group header is a descriptive text preceding an option group. For example, in the following text:

 Sieve options
  -I, --includedir=DIR       Append directory DIR to the
                             list of include directories

the text ‘Sieve options’ is a group header.

The default value is 1.

Help Output: offset usage-indent

Indentation of wrapped usage lines. Affects --usage output. Default is 12.

Help Output: offset rmargin

Right margin of the text output. Used for wrapping.

GNU Mailutils Manual:   Section:   Chapter:FastBack: Usage Vars   Up: Top   FastForward: Function Index   Contents: Table of ContentsIndex: Function Index

Appendix D GNU Free Documentation License

Version 1.2, November 2002
Copyright © 2000-2002, 2010-2012, 2014-2016 Free Software
Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

    A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

    The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

    A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

    The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.

    A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.

    The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    13. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
    14. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
    15. Preserve any Warranty Disclaimers.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.

    You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

    If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

D.1 ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.2
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:

    with the Invariant Sections being list their titles, with
    the Front-Cover Texts being list, and with the Back-Cover Texts
    being list.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

GNU Mailutils Manual:   Section:   Chapter:FastBack: GNU FDL   Up: Top   FastForward: Variable Index   Contents: Table of ContentsIndex: Function Index

Function Index

This is an alphabetical list of all Mailutils functions.

Jump to:   A   B   C   D   E   F   G   H   I   K   L   M   N   O   P   Q   R   S   T   U   V   W   Y  
Index Entry  Section
A
acl: Server Statement
address: Built-in Tests
ago in date strings: Relative items in date strings
allow: acl statement
allow-biffrc: General Settings
allow-table: tcp-wrappers statement
am in date strings: Time of day items
append: mailutils imap
auth: radius statement
auth: mailutils smtp
authentication: auth statement
authorization: auth statement
B
backlog: Server Statement
base: ldap statement
binddn: ldap statement
bulletin-db: Conf-pop3d
bulletin-source: Conf-pop3d
C
ca-file-safety-checks: tls statement
capa: mailutils smtp
capability: mailutils imap
cert-file-safety-checks: tls statement
check: mailutils imap
clear: mailutils smtp
clear-include-path: Sieve Configuration
clear-library-path: Sieve Configuration
close: mailutils imap
concat: Format String Diffs
config-file, --config-file option, described: configuration
config-file, --config-file option, introduced: Common Options
config-help, --config-help option, described: configuration
config-help, --config-help option, introduced: Common Options
config-lint, --config-lint option, described: configuration
config-lint, --config-lint option, introduced: Common Options
config-verbose, --config-verbose option, described: configuration
config-verbose, --config-verbose option, introduced: Common Options
connect: mailutils imap
connect: mailutils smtp
create: mailutils imap
create-home-dir: Conf-imap4d
D
daemon: tcp-wrappers statement
day in date strings: Relative items in date strings
day in date strings: Relative items in date strings
db: sql statement
debug: ldap statement
debug: Sieve Configuration
debug: Conf-maidag
debug: Mimeview Config
decode: Format String Diffs
delete: mailutils imap
delete-expired: Conf-pop3d
deny: acl statement
deny-table: tcp-wrappers statement
directory: radius statement
discard: Built-in Actions
disconnect: mailutils imap
E
ehlo: mailutils smtp
emacs: Movemail Configuration
email: Sieve Configuration
enable: tcp-wrappers statement
enable: ldap statement
enable: tls statement
envelope: Built-in Tests
ex-multiple-delivery-success: Conf-maidag
ex-quota-tempfail: Conf-maidag
examine: mailutils imap
exec: acl statement
exec: acl statement
exists: Built-in Tests
expire: Conf-pop3d
expire-timeout: locking statement
expunge: mailutils imap
external-locker: locking statement
F
facility: logging statement
false: Built-in Tests
fetch: mailutils imap
field-map: sql statement
field-map: ldap statement
fileinto: Built-in Actions
first in date strings: General date syntax
flags: locking statement
folder: mailbox statement
folder: Conf-readmsg
foreground: General Server Configuration
form-feeds: Conf-readmsg
fortnight in date strings: Relative items in date strings
forward-file: Conf-maidag
forward-file-checks: Conf-maidag
from: mailutils smtp
G
getpass: sql statement
getpwnam: radius statement
getpwnam: sql statement
getpwnam: ldap statement
getpwuid: radius statement
getpwuid: sql statement
getpwuid: ldap statement
get_date: Date Input Formats
group: Conf-maidag
guile-filter: Conf-maidag
guimb-end: guimb
guimb-getopt: guimb
guimb-message: guimb
H
header: Conf-readmsg
header: Built-in Tests
help, --help option, described: Common Options
home-dir-mode: Conf-imap4d
host: sql statement
hour in date strings: Relative items in date strings
I
id: mailutils imap
id-fields: Conf-imap4d
ident-encrypt-only: Conf-imap4d
ident-keyfile: Conf-imap4d
ifexec: acl statement
ignore-errors: Movemail Configuration
include-path: Sieve Configuration
interface: sql statement
in_reply_to: Format String Diffs
isreply: Format String Diffs
K
keep: Built-in Actions
keep-going: Sieve Configuration
key-file-safety-checks: tls statement
L
last day: Day of week items
last in date strings: General date syntax
library-path: Sieve Configuration
library-path-prefix: Sieve Configuration
line-info: Sieve Configuration
list: mailutils imap
list: mailutils smtp
list: External Tests
listen: Conf-maidag
lmtp: Conf-maidag
log: acl statement
login: mailutils imap
login-delay: Conf-pop3d
login-disabled: Conf-imap4d
logout: mailutils imap
lsub: mailutils imap
M
mail-spool: mailbox statement
mailbox-ownership: Movemail Configuration
mailbox-pattern: mailbox statement
mailbox-type: mailbox statement
max-children: General Server Configuration
max-lines: General Settings
max-messages: Movemail Configuration
max-requests: Security Settings
mbox-url: Sieve Configuration
message-id-header: Conf-maidag
metamail: Mimeview Config
midnight in date strings: Time of day items
mimetypes: Mimeview Config
minute in date strings: Relative items in date strings
mode: General Server Configuration
moderator: External Actions
month in date strings: Relative items in date strings
N
next day: Day of week items
next in date strings: General date syntax
no-config, --no-config option, introduced: Common Options
no-header: Conf-readmsg
no-site-config, --no-site-config option, described: configuration
no-site-config, --no-site-config option, introduced: Common Options
no-user-config, --no-user-config option, described: configuration
no-user-config, --no-user-config option, introduced: Common Options
noon in date strings: Time of day items
noop: mailutils imap
now in date strings: Relative items in date strings
numaddr: External Tests
O
onerror: Movemail Configuration
other-mailbox-mode: Conf-imap4d
other-namespace: Conf-imap4d
overflow-control-interval: Security Settings
overflow-delay-time: Security Settings
P
package: Format String Diffs
package_string: Format String Diffs
passwd: sql statement
passwd: ldap statement
passwd-dir: virtdomain statement
password-encryption: sql statement
pidfile: General Server Configuration
pipe: External Tests
pipe: External Actions
pm in date strings: Time of day items
port: General Server Configuration
port: sql statement
preauth: Conf-imap4d
preauth-only: Conf-imap4d
preserve: Movemail Configuration
print-severity: logging statement
printhdr: Format String Diffs
program-id: Movemail Configuration
Q
quit: mailutils imap
quit: mailutils smtp
quota-db: Conf-maidag
R
rcpt: Format String Diffs
redirect: Built-in Actions
references: Format String Diffs
reject: Built-in Actions
rename: mailutils imap
reply_regex: Format String Diffs
request-control-interval: Security Settings
retry-count: locking statement
retry-timeout: locking statement
reuse-address: Conf-maidag
reverse: Movemail Configuration
rset: mailutils smtp
S
select: mailutils imap
send: mailutils smtp
service: pam statement
session-id: logging statement
set: mailutils smtp
set, --set option, described: configuration
set, --set option, introduced: Common Options
severity: logging statement
shared-mailbox-mode: Conf-imap4d
shared-namespace: Conf-imap4d
show-all-match: Conf-readmsg
show-config-options, --show-config-options option, described: Common Options
sieve: Sieve Configuration
sieve-filter: Conf-maidag
single-process: Server Statement
size: Built-in Tests
smtp: mailutils smtp
spamd: External Tests
ssl-cafile: tls statement
ssl-cert: tls statement
ssl-key: tls statement
ssl-priorities: tls statement
starttls: mailutils imap
starttls: mailutils smtp
stat-file: Conf-pop3d
status: mailutils imap
stderr: Conf-maidag
stop: Built-in Actions
store: mailutils imap
subscribe: mailutils imap
syslog: logging statement
T
tag: logging statement
this in date strings: Relative items in date strings
ticket: Sieve Configuration
timeout: General Server Configuration
timeout: Server Statement
timestamp: External Tests
tls: Server Statement
tls: ldap statement
tls-required: Conf-pop3d
tls-required: Conf-imap4d
to: mailutils smtp
today in date strings: Relative items in date strings
tomorrow in date strings: Relative items in date strings
transcript: Server Statement
true: Built-in Tests
U
uid: mailutils imap
uidl: Movemail Configuration
undelete: Conf-pop3d
unre: Format String Diffs
unselect: mailutils imap
unsubscribe: mailutils imap
url: mailer statement
url: ldap statement
usage, --usage option, described: Common Options
user: sql statement
V
vacation: External Actions
verbose: Movemail Configuration
verbose: Sieve Configuration
version: Format String Diffs
version, --version option, described: Common Options
W
weedlist: Conf-readmsg
week in date strings: Relative items in date strings
Y
year in date strings: Relative items in date strings
yesterday in date strings: Relative items in date strings
Jump to:   A   B   C   D   E   F   G   H   I   K   L   M   N   O   P   Q   R   S   T   U   V   W   Y  

GNU Mailutils Manual:   Section:   Chapter:FastBack: Function Index   Up: Top   FastForward: Keyword Index   Contents: Table of ContentsIndex: Function Index

Variable Index

Jump to:   A   B   C   D   E   F   H   I   K   L   M   N   O   P   Q   R   S   T   U   V   X  
Index Entry  Section
A
append, mail variable: Mail Variables
append, mail variable: Mail Variables
appenddeadletter, mail variable: Mail Variables
ARGP_HELP_FMT, environment variable: Usage Vars
askbcc, mail variable: Mail Variables
askcc, mail variable: Mail Variables
asksub, mail variable: Mail Variables
autoinc, mail variable: Mail Variables
autoprint, mail variable: Mail Variables
B
bang, mail variable: Mail Variables
byname, mail variable: Mail Variables
C
charset, mail variable: Mail Variables
cmd, mail variable: Mail Variables
columns, mail variable: Mail Variables
crt, mail variable: Mail Variables
D
datefield, mail variable: Mail Variables
debug, mail variable: Mail Variables
debug, mail variable: Mail Variables
decode-fallback, mail variable: Mail Variables
doc-opt-col: Usage Vars
dot, mail variable: Mail Variables
dup-args: Usage Vars
dup-args-note: Usage Vars
E
editheaders, mail variable: Mail Variables
emptystart, mail variable: Mail Variables
escape, mail variable: Mail Variables
F
flipr, mail variable: Mail Variables
folder, mail variable: Mail Variables
H
header, mail variable: Mail Variables
header-col: Usage Vars
hold, mail variable: Mail Variables
I
ignore, mail variable: Mail Variables
ignoreeof, mail variable: Mail Variables
indentprefix, mail variable: Mail Variables
K
keepsave, mail variable: Mail Variables
L
LD_LIBRARY_PATH: Require Statement
long-opt-col: Usage Vars
LTDL_LIBRARY_PATH: Require Statement
M
mailx, mail variable: Mail Variables
metamail, mail variable: Mail Variables
metoo, mail variable: Mail Variables
mimenoask, mail variable: Mail Variables
mode, mail variable: Mail Variables
MU_DEFAULT_SCHEME: mailbox statement
N
nullbody, mail variable: Mail Variables
nullbodymsg: Mail Variables
O
onehop, mail variable: Mail Variables
opt-doc-col: Usage Vars
outfolder, mail variable: Mail Variables
P
page, mail variable: Mail Variables
prompt, mail variable: Mail Variables
Q
quiet, mail variable: Mail Variables
quit, mail variable: Mail Variables
R
rc, mail variable: Mail Variables
readonly, mail variable: Mail Variables
record, mail variable: Mail Variables
regex, mail variable: Mail Variables
replyprefix, mail variable: Mail Variables
replyregex, mail variable: Mail Variables
return-address, mail variable.: Mail Variables
rmargin: Usage Vars
S
save, mail variable: Mail Variables
screen, mail variable: Mail Variables
sendmail, mail variable: Mail Variables
sendwait, mail variable: Mail Variables
short-opt-col: Usage Vars
showto, mail variable: Mail Variables
showto, mail variable: Mail Variables
Sign, mail variable: Mail Variables
sign, mail variable: Mail Variables
string: Profile Variable Diffs
string: Profile Variable Diffs
subject, mail variable: Mail Variables
T
toplines, mail variable: Mail Variables
TZ: Specifying time zone rules
U
usage-indent: Usage Vars
V
verbose, mail variable: Mail Variables
X
xmailer, mail variable: Mail Variables
Jump to:   A   B   C   D   E   F   H   I   K   L   M   N   O   P   Q   R   S   T   U   V   X  

GNU Mailutils Manual:   Section:   Chapter:FastBack: Variable Index   Up: Top   FastForward: Program Index   Contents: Table of ContentsIndex: Function Index

Keyword Index

Jump to:   !   #   :   =   ?   |   ~  
A   B   C   D   E   F   G   H   I   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Z  
Index Entry  Section
!
!, mail command: Shell Escapes
#
#include, sieve: #include
#searchpath, sieve: #searchpath
:
:all, sieve: Tests
:comparator, sieve: Tests
:contains, sieve: Tests
:count, sieve: Tests
:domain, sieve: Tests
:is, sieve: Tests
:localpart, sieve: Tests
:matches, sieve: Tests
:mime: Built-in Tests
:over: Built-in Tests
:over: External Tests
:regex, sieve: Tests
:under: Built-in Tests
:under: External Tests
:value, sieve: Tests
=
=, mail command: Displaying Information
?
?, mail command: Obtaining Online Help
|
|, mail command: Displaying Messages
~
~!, mail escape: Executing Shell Commands
~-, mail escape: Executing Other Mail Commands
~., mail escape: Quitting Compose Mode
~:, mail escape: Executing Other Mail Commands
~?, mail escape: Getting Help on Compose Escapes
~a, mail escape: Signing the Message
~A, mail escape: Signing the Message
~e, mail escape: Editing the Message
~f, mail escape: Printing Another Message
~F, mail escape: Printing Another Message
~i, mail escape: Inserting Value of a Mail Variable
~m, mail escape: Enclosing Another Message
~M, mail escape: Enclosing Another Message
~p, mail escape: Printing And Saving the Message
~v, mail escape: Editing the Message
~w, mail escape: Printing And Saving the Message
~x, mail escape: Quitting Compose Mode
~|, mail escape: Executing Shell Commands
A
acl: acl statement
alias, mail command: Aliasing
all, sieve: Tests
allof: Tests and Conditions
alternates, mail command: Aliasing
and, sieve: Tests and Conditions
any: acl statement
anyof: Tests and Conditions
append: Mail Variables
appenddeadletter: Mail Variables
askbcc: Mail Variables
askcc: Mail Variables
asksub: Mail Variables
auth: auth statement
autoinc: Mail Variables
autoprint: Mail Variables
B
bang: Mail Variables
byname: Mail Variables
C
charset: Mail Variables
chdir, mail command: Changing mailbox/directory
cmd: Mail Variables
columns: Mail Variables
comparator, sieve: Tests
contains, sieve: Tests
copy, mail command: Saving Messages
Copy, mail command: Saving Messages
count, sieve: Tests
crt: Mail Variables
D
datefield: Mail Variables
debug: debug statement
debug: Mail Variables
debug: Mail Variables
decode, mail command: Displaying Messages
decode-fallback: Mail Variables
delete, mail command: Disposing of Messages
discard, mail command: Controlling Header Display
domain: SMTP Mailboxes
domain, sieve: Tests
dot: Mail Variables
dp, mail command: Disposing of Messages
dt, mail command: Disposing of Messages
E
echo, mail command: Scripting
edit, mail command: Editing Messages
editheaders: Mail Variables
else, mail command: Scripting
emptystart: Mail Variables
endif, mail command: Scripting
escape: Mail Variables
F
file, mail command: Changing mailbox/directory
flipr: Mail Variables
folder: Mail Variables
folder, mail command: Changing mailbox/directory
folders, mail command: Displaying Information
followup, mail command: Replying
Followup, mail command: Replying
forward-file: Forwarding
forward-file-checks: Forwarding
from: SMTP Mailboxes
from, mail command: Displaying Information
fromfield: Mail Variables
G
GNU-MU-Dir: radius statement
GNU-MU-GECOS: radius statement
GNU-MU-GID: radius statement
GNU-MU-Mailbox: radius statement
GNU-MU-Quota: radius statement
GNU-MU-Shell: radius statement
GNU-MU-UID: radius statement
GNU-MU-User-Name: radius statement
group, mail command: Aliasing
gsasl: gsasl statement
H
header: Mail Variables
headers, mail command: Displaying Information
headline: Mail Variables
help, mail command: Obtaining Online Help
hold: Mail Variables
hold, mail command: Marking Messages
I
if, mail command: Scripting
if, sieve: Control Flow
ignore: Mail Variables
ignore, mail command: Controlling Header Display
ignoreeof: Mail Variables
include: include
incorporate, mail command: Incorporating New Mail
indentprefix: Mail Variables
inplacealiases: Mail Variables
is, sieve: Tests
K
keep: Mail Variables
keepsave: Mail Variables
L
ldap: ldap statement
level: debug statement
line-info: debug statement
list, mail command: Obtaining Online Help
localpart, sieve: Tests
locking: locking statement
logging: logging statement
M
mail, mail command: Replying
mailbox: mailbox statement
mailer: mailer statement
mailx: Mail Variables
matches, sieve: Tests
mbox, mail command: Saving Messages
metamail: Mail Variables
metoo: Mail Variables
mimenoask: Mail Variables
mode: Mail Variables
N
next, mail command: Moving Within a Mailbox
noauth: SMTP Mailboxes
nosender, mail command: Controlling Sender Fields
not, sieve: Tests and Conditions
notls: SMTP Mailboxes
nullbody: Mail Variables
nullbodymsg: Mail Variables
O
onehop: Mail Variables
or, sieve: Tests and Conditions
outfolder: Mail Variables
P
page: Mail Variables
pam: pam statement
param: mailbox statement
pipe, mail command: Displaying Messages
preserve, mail command: Marking Messages
prev, mail command: Moving Within a Mailbox
print, mail command: Displaying Messages
Print, mail command: Displaying Messages
program: program statement
prompt: Mail Variables
Q
quiet: Mail Variables
quit: Mail Variables
R
radius: radius statement
rc: Mail Variables
rcpt: Program Mailboxes
readonly: Mail Variables
record: Mail Variables
recursivealiases: Mail Variables
regex: Mail Variables
regex, sieve: Tests
reply, mail command: Replying
Reply, mail command: Replying
replyprefix: Mail Variables
replyregex: Mail Variables
require, sieve: Require Statement
respond, mail command: Replying
Respond, mail command: Replying
retain, mail command: Controlling Header Display
return-address: Mail Variables
S
save: Mail Variables
save, mail command: Saving Messages
Save, mail command: Saving Messages
screen: Mail Variables
script: Sieve Maidag Filters
script: Scheme Maidag Filters
script: Python Maidag Filters
sender: Program Mailboxes
sender, mail command: Controlling Sender Fields
sendmail: Mail Variables
sendwait: Mail Variables
server: Server Statement
set, mail command: Scripting
shell, mail command: Shell Escapes
showenvelope: Mail Variables
showto: Mail Variables
showto: Mail Variables
Sign: Mail Variables
sign: Mail Variables
size, mail command: Displaying Information
source, mail command: Scripting
sql: sql statement
strip-domain: SMTP Mailboxes
struct, mail command: Displaying Messages
subject: Mail Variables
summary, mail command: Displaying Information
T
tag, mail command: Marking Messages
tcp-wrappers: tcp-wrappers statement
text:: Lexical Structure
tls: tls statement
to: SMTP Mailboxes
top, mail command: Displaying Messages
toplines: Mail Variables
touch, mail command: Saving Messages
type: mailbox statement
type, mail command: Displaying Messages
Type, mail command: Displaying Messages
U
unalias, mail command: Aliasing
undelete, mail command: Disposing of Messages
unset, mail command: Scripting
user: mailbox statement
V
value, sieve: Tests
variable, mail command: Scripting
variable-pretty-print: Mail Variables
variable-strict: Mail Variables
verbose: Mail Variables
version, mail command: Obtaining Online Help
virtdomain: virtdomain statement
visual, mail command: Editing Messages
W
warranty, mail command: Obtaining Online Help
write, mail command: Saving Messages
Write, mail command: Saving Messages
X
xmailer: Mail Variables
Z
z, mail command: Displaying Information
Jump to:   !   #   :   =   ?   |   ~  
A   B   C   D   E   F   G   H   I   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Z  

GNU Mailutils Manual:   Section:   Chapter:FastBack: Keyword Index   Up: Top   FastForward: Concept Index   Contents: Table of ContentsIndex: Function Index

Program Index

Jump to:   C   F   G   I   M   P   R   S  
Index Entry  Section
C
comsatd: comsatd
F
frm: frm and from
from: frm and from
G
guimb: guimb
I
imap4d: imap4d
M
maidag: maidag
mail: mail
mailutils: mailutils
messages: messages
mimeview: mimeview
movemail: movemail
P
pop3d: pop3d
R
readmsg: readmsg
S
sieve: sieve
Jump to:   C   F   G   I   M   P   R   S  

GNU Mailutils Manual:   Section:   Chapter:FastBack: Program Index   Up: Top     Contents: Table of ContentsIndex: Function Index

Concept Index

This is a general index of all issues discussed in this manual

Jump to:   ~  
A   B   C   D   E   F   G   H   I   L   M   N   O   P   Q   R   S   T   U   V  
Index Entry  Section
~
~+, mail escape: Attaching a File to the Message
~<, mail escape: Adding a File to the Message
~b, mail escape: Modifying the Headers
~c, mail escape: Modifying the Headers
~d, mail escape: Adding a File to the Message
~h, mail escape: Modifying the Headers
~l, mail escape: Attaching a File to the Message
~r, mail escape: Adding a File to the Message
~s, mail escape: Modifying the Headers
~t, mail escape: Modifying the Headers
~^, mail escape: Attaching a File to the Message
A
abbreviations for months: Calendar date items
action, sieve: Actions Described
authentication: auth statement
authorization: auth statement
authors of get_date: Authors of get_date
B
beginning of time, for POSIX: Seconds since the Epoch
Bellovin, Steven M.: Authors of get_date
Berets, Jim: Authors of get_date
Bernstein, D. J.: Local Mailboxes
Berry, K.: Authors of get_date
block statement: Statements
boolean value: Statements
C
calendar date item: Calendar date items
case, ignored in dates: General date syntax
Comments in a configuration file: Comments
comments, in dates: General date syntax
comparator, sieve: Comparators
condition, sieve: Tests and Conditions
configuration file statements: Statements
configuring servers: Server Settings
D
daemon, server mode: General Server Configuration
date format, ISO 8601: Calendar date items
date input formats: Date Input Formats
day of week item: Day of week items
direct indexing: mailbox statement
directory indexing: mailbox statement
displacement of dates: Relative items in date strings
E
Eggert, Paul: Authors of get_date
epoch, for POSIX: Seconds since the Epoch
escape sequence: Statements
Exim: Exim-maidag
F
FDL, GNU Free Documentation License: GNU FDL
file, mailbox type: Local Mailboxes
forward: Forwarding
G
general date syntax: General date syntax
H
hashed indexing: mailbox statement
here-document: Statements
I
imap, mailbox: Remote Mailboxes
IMAP4 namespace: Namespace
imaps, mailbox: Remote Mailboxes
include statement, configuration file: include
indexing, direct: mailbox statement
indexing, hashed: mailbox statement
indexing, reverse: mailbox statement
inetd, server mode: General Server Configuration
ISO 8601 date format: Calendar date items
items in date strings: General date syntax
L
language, in dates: General date syntax
language, in dates: General date syntax
Libraries: Libraries
list: Statements
LMTP: MeTA1-maidag
local mailbox: Local Mailboxes
M
MacKenzie, David: Authors of get_date
macro variable: Variables
mailbox URL: Mailbox
mailbox, local: Local Mailboxes
mailbox, program: Program Mailboxes
mailbox, remote: Remote Mailboxes
mailbox, SMTP: SMTP Mailboxes
maildir: Local Mailboxes
mailman: External Actions
Mailutils configuration file: configuration
mailutils.conf: configuration
mailutils.dict: radius statement
mbox: Local Mailboxes
MeTA1: MeTA1-maidag
Meyering, Jim: Authors of get_date
mh: Local Mailboxes
minutes, time zone correction by: Time of day items
month names in date strings: Calendar date items
months, written-out: General date syntax
movemail, configuration: Movemail Configuration
multi-line comments: Comments
multiline strings, sieve: Lexical Structure
N
namespace: Namespace
numbers, sieve: Lexical Structure
numbers, written-out: General date syntax
O
ordinal numbers: General date syntax
P
Pinard, F.: Authors of get_date
plus expansion: mailbox statement
pop, mailbox: Remote Mailboxes
pops, mailbox: Remote Mailboxes
preprocessor, sieve: Preprocessor
prog, URL: Program Mailboxes
program mailbox: Program Mailboxes
Programs: Programs
pure numbers in date strings: Pure numbers in date strings
Q
quoted string: Statements
R
RAND Corporation: Local Mailboxes
relative items in date strings: Relative items in date strings
remote mailbox: Remote Mailboxes
reverse indexing: mailbox statement
S
Salz, Rich: Authors of get_date
Sendmail: Sendmail-maidag
sendmail, URL: Program Mailboxes
server configuration, general: General Server Configuration
server settings, configuration: Server Settings
server statement: Server Statement
Sieve Language: Sieve Language
Sieve preprocessor statements: Preprocessor
simple statements: Statements
single-line comments: Comments
smtp, mailbox: SMTP Mailboxes
smtps, mailbox: SMTP Mailboxes
statement, block: Statements
statement, simple: Statements
statements, configuration file: Statements
string list, sieve: Lexical Structure
string, quoted: Statements
string, unquoted: Statements
strings, sieve: Lexical Structure
T
test, sieve: Tests and Conditions
test, sieve: Tests
time of day item: Time of day items
time zone correction: Time of day items
time zone item: General date syntax
time zone item: Time zone items
U
URL, local: Local Mailboxes
URL, mailbox: Mailbox
URL, prog: Program Mailboxes
URL, remote: Remote Mailboxes
URL, sendmail: Program Mailboxes
URL, SMTP: SMTP Mailboxes
V
variable expansion: Variables
Jump to:   ~  
A   B   C   D   E   F   G   H   I   L   M   N   O   P   Q   R   S   T   U   V  

Footnotes

(1)

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

(2)

Rmail does not use this feature

(3)

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.

(4)

See http://www.faqs.org/rfcs/rfc3501.html.

(5)

http://www.faqs.org/rfcs/rfc2971.html

(6)

http://tools.ietf.org/html/rfc3501#section-6.4.5

(7)

http://tools.ietf.org/html/rfc3501#section-6.4.6

(8)

http://tools.ietf.org/html/rfc3501#section-6.3.8

(9)

http://tools.ietf.org/html/rfc3501#section-6.3.9