This is mailutils.info, produced by makeinfo version 6.7 from
mailutils.texi.

Published by the Free Software Foundation, 51 Franklin Street, Fifth
Floor Boston, MA 02110-1301, USA

   Copyright (C) 1999-2024 Free Software Foundation, Inc.

   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, and no Back-Cover texts.  A copy of
the license is included in the section entitled "GNU Free Documentation
License".
INFO-DIR-SECTION Email
START-INFO-DIR-ENTRY
* Mailutils: (mailutils).       GNU Mail Utilities.
END-INFO-DIR-ENTRY

INFO-DIR-SECTION Individual utilities
START-INFO-DIR-ENTRY
* comsatd: (mailutils) comsatd.          Comsat Daemon.
* frm: (mailutils) frm.                  List Headers from a Mailbox.
* guimb: (mailutils) guimb.              Mailbox Processing Language.
* imap4d: (mailutils) imap4d.            IMAP4 Daemon.
* mail: (mailutils) mail.                Send and Receive Mail.
* maidag: (mailutils) maidag.            A General-Purpose Mail Delivery Agent.
* messages: (mailutils) messages.        Count Messages in a Mailbox.
* movemail: (mailutils) movemail.        Move Mail between Mailboxes.
* pop3d: (mailutils) pop3d.              POP3 Daemon.
* readmsg: (mailutils) readmsg.          Extract Messages from a Folder.
* decodemail: (mailutils) decodemail.    Decode MIME messages.
* sieve: (mailutils) sieve.              Mail Filtering Utility.
* mimeview: (mailutils) mimeview.        View MIME Messages.
* mailutils: (mailutils) mailutils.      Mailutils Multi-Purpose Tool
END-INFO-DIR-ENTRY


File: mailutils.info,  Node: Top,  Next: Introduction,  Up: (dir)

GNU Mailutils
*************

This edition of the 'GNU Mailutils Manual', last updated on 6 January
2024, documents GNU Mailutils Version 3.17.

* Menu:

* Introduction::            Preliminary Information.
* Mailbox::                 Mailboxes and URLs.
* Programs::                Mailutils Programs.
* Libraries::               Mailutils Libraries.
* Sieve Language::          The Sieve Language.
* Reporting Bugs::          How to Report a Bug.
* News::                    Getting News About GNU Mailutils.
* Acknowledgement::         Thanks and Credits.

Appendices

* References::              References.
* Date Input Formats::
* Date/time Format String::
* Usage Vars::              Configuring Help Summary
* GNU FDL::                 This manual is under the GNU Free
                            Documentation License.

Indices

* Function Index::          All Mailutils Functions.
* Variable Index::          All Mailutils Variables.
* Keyword Index::           Index of Keywords.
* Program Index::           All Mailutils Programs.
* Concept Index::           Index of Concepts.

 -- The Detailed Node Listing --

Introduction

* Book Contents::               What this Book Contains
* History::                     A bit of History

Mailbox

* Local Mailboxes::      Mailboxes stored on the local file system.
* Remote Mailboxes::     Mailboxes stored on remote hosts.
* SMTP Mailboxes::       Mailboxes that send mail.
* Program Mailboxes::

Mailutils Programs

* command line::      Command Line Syntax.
* configuration::     Common Configuration File.
* debugging::

* frm and from::      List Headers from a Mailbox.
* mail::              Send and Receive Mail.
* messages::          Count the Number of Messages in a Mailbox.
* movemail::          Moves Mail from the User Maildrop to the Local File.
* readmsg::           Extract Messages from a Folder.
* decodemail::        Decode multipart messages.

* sieve::             Mail Filtering Utility.
* guimb::             Mailbox Scanning and Processing Language.

* mda::               Local Mail Delivery Agent.
* lmtpd::             LMTP Daemon.
* putmail::           Incorporate a Message to a Mailbox.

* mimeview::          Universal File Viewer.

* pop3d::             POP3 Daemon.
* imap4d::            IMAP4 Daemon.
* comsatd::           Comsat Daemon.

* mh::                The MH Message Handling System.

* mailutils::         The Mailutils Multi-Purpose Tool.
* dotlock::           The External Locker Utility.

Command Line

* Option Basics::       Basic Notions About Command Line Options.
* Common Options::      Options That are Common for All Utilities.

Mailutils Configuration File

* conf-syntax::         Configuration File Syntax
* Variables::           Variable Expansion
* include::             Include Statement
* program statement::
* logging statement::
* debug statement::
* mailbox statement::
* mime statement::
* locking statement::
* mailer statement::
* acl statement::
* tcp-wrappers statement::
* Server Settings::
* auth statement::
* pam statement::
* virtdomain statement::
* radius statement::
* sql statement::
* ldap statement::
* tls statement::
* tls-file-checks statement::
* gsasl statement::

Configuration File Syntax

* Comments::
* Statements::
* Paths::

Server Settings

* General Server Configuration::
* Server Statement::

Debugging

* Level Syntax::
* Level BNF::
* Debugging Categories::

'mail' -- Send and Receive Mail

* Invoking Mail::            Command Line Options.
* Reading Mail::             Reading Mail.
* Saving and Recording::     Where Mail Messages are Stored.
* Composing Mail::           Composing Mail.
* MIME::                     How to Attach Files.
* Scripting::                Scripting.
* Mail Variables::           How to Alter the Behavior of 'mail'.
* Mail Configuration Files:: Personal and System-wide Configuration Files.

Reading Mail

* Command Syntax::           Syntax of mail internal commands.
* Quitting the Program::
* Obtaining Online Help::
* Moving Within a Mailbox::
* Changing mailbox/directory::
* Controlling Header Display::
* Displaying Information::
* Displaying Messages::
* Marking Messages::
* Disposing of Messages::
* Saving Messages::
* Editing Messages::
* Aliasing::
* Replying::
* Controlling Sender Fields::
* Incorporating New Mail::
* Shell Escapes::

Composing Mail

* Quitting Compose Mode::
* Getting Help on Compose Escapes::
* Editing the Message::
* Modifying the Headers::
* Enclosing Another Message::
* Adding a File to the Message::
* Attaching a File to the Message::
* Printing And Saving the Message::
* Signing the Message::
* Printing Another Message::
* Inserting Value of a Mail Variable::
* Executing Other Mail Commands::
* Executing Shell Commands::

'movemail' -- Moves Mail from the User Maildrop to the Local File

* Movemail Configuration::
* Ownership::            Setting Destination Mailbox Ownership
* Summary::              Short Movemail Invocation Summary

'readmsg' -- Extract Messages from a Folder

* Opt-readmsg::   Invocation of 'readmsg'.
* Conf-readmsg::  Configuration of 'readmsg'.

'decodemail' - Decode multipart messages

* Opt-decodemail::   Invocation of 'decodemail'.
* Conf-decodemail::  Configuration of 'decodemail'.
* Using-decodemail:: Purpose and caveats of 'decodemail'.

'sieve'

* sieve interpreter::   A Sieve Interpreter

A Sieve Interpreter

* Invoking Sieve::
* Sieve Configuration::
* Logging and Debugging::
* Extending Sieve::

'guimb' -- A Mailbox Scanning and Processing Language

* Specifying Scheme Program to Execute::
* Specifying Mailboxes to Operate Upon::
* Passing Options to Scheme::
* Command Line Option Summary::

mda

* Sendmail-mda::         Using 'mda' with Sendmail.
* Exim-mda::             Using 'mda' with Exim.
* MeTA1-mda::            Using 'mda' with MeTA1.
* Mailbox Quotas::
* MDA Scripting::
* Forwarding::
* Conf-mda::             'mda' Configuration File Summary.
* Mailing lists::        How to implement Mailing Lists with 'mda'.

Mailbox Quotas

* DBM Quotas::          Keeping Quotas in DBM File.
* SQL Quotas::          Keeping Quotas in SQL Database.

Scripting in 'mda'

* Sieve MDA Filters::
* Scheme MDA Filters::
* Python MDA Filters::

lmtpd

* MeTA1-lmtpd:: Using 'lmtpd' with MeTA1.

putmail

* putmail options::
* putmail configuration::

mimeview

* Mimeview Invocation::
* Mimeview Config::

POP3 Daemon

* Login delay::
* Auto-expire::
* Bulletins::
* Conf-pop3d::           Pop3d Configuration
* Command line options::

IMAP4 Daemon

* Namespace::       Namespace.
* Conf-imap4d::     Configuration.
* Starting imap4d:: Invocation Options.

Comsat Daemon

* Starting comsatd::       Invocation.
* Configuring comsatd::    Configuration of 'comsatd'.
* dot.biffrc::             A per-user configuration file.

Configuring 'comsatd'

* General Settings::
* Security Settings::

MH -- The MH Message Handling System

* Diffs::      Major differences between Mailutils MH and other MH
               implementations.

Major differences between Mailutils MH and other MH implementations

* Format String Diffs::
* Profile Variable Diffs::
* Program Diffs::

mailutils

* mailutils invocation syntax::
* mailutils help::                Display a terse help summary.
* mailutils info::                Show Mailutils configuration.
* mailutils cflags::              Show compiler options.
* mailutils ldflags::             List libraries required to link.
* mailutils stat::                Show mailbox status.
* mailutils query::               Query configuration values.
* mailutils 2047::                Decode/encode email message headers.
* mailutils filter::              Apply a chain of filters to the input.
* mailutils acl::                 Test access control lists.
* mailutils wicket::              Scan wickets for matching URLs.
* mailutils dbm::                 DBM management tool.
* mailutils logger::              Log data using Mailutils log facility.
* mailutils pop::                 POP3 client shell.
* mailutils imap::                IMAP4 client shell.
* mailutils send::                Send a message.
* mailutils smtp::                Run a SMTP session.
* mailutils maildir_fixup::       Fix-up maildirs created by versions prior to 3.10.90

mailutils dbm

* Create a Database::
* Add Records to a Database::
* Delete Records::
* List the Database::
* Dump the Database::
* Dump Formats::
* Dbm Exit Codes::

Sieve Language

* Lexical Structure::
* Syntax::
* Preprocessor::
* Require Statement::
* Comparators::
* Tests::
* Actions::
* Extensions::
* GNU Extensions::

Syntax

* Commands::
* Actions Described::
* Control Flow::
* Tests and Conditions::

Preprocessor

* #include::        Include the contents of a file.
* #searchpath::     Modify the current search path.

Tests

* Built-in Tests::
* External Tests::

Actions

* Built-in Actions::
* External Actions::

Extensions

* encoded-character::
* relational::
* variables::
* environment::
* numaddr::
* editheader::
* list::
* moderator::
* pipe::
* spamd::
* timestamp::
* vacation::

Date Input Formats

* General date syntax::            Common rules.
* Calendar date items::            19 Dec 1994.
* Time of day items::              9:20pm.
* Time zone items::                EST, PDT, GMT.
* Day of week items::              Monday and others.
* Relative items in date strings:: next tuesday, 2 years ago.
* Pure numbers in date strings::   19931219, 1440.
* Seconds since the Epoch::        @1078100502.
* Specifying time zone rules::     TZ="America/New_York", TZ="UTC0".
* Authors of get_date::            Bellovin, Eggert, Salz, Berets, et al.



File: mailutils.info,  Node: Introduction,  Next: Mailbox,  Prev: Top,  Up: Top

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.

* Menu:

* Book Contents::               What this Book Contains
* History::                     A bit of History


File: mailutils.info,  Node: Book Contents,  Next: History,  Up: Introduction

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


File: mailutils.info,  Node: History,  Prev: Book Contents,  Up: Introduction

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.


File: mailutils.info,  Node: Mailbox,  Next: Programs,  Prev: Introduction,  Up: Top

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.

* Menu:

* Local Mailboxes::      Mailboxes stored on the local file system.
* Remote Mailboxes::     Mailboxes stored on remote hosts.
* SMTP Mailboxes::       Mailboxes that send mail.
* Program Mailboxes::


File: mailutils.info,  Node: Local Mailboxes,  Next: Remote Mailboxes,  Up: Mailbox

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.  *Note 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.


File: mailutils.info,  Node: Remote Mailboxes,  Next: SMTP Mailboxes,  Prev: Local Mailboxes,  Up: Mailbox

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.


File: mailutils.info,  Node: SMTP Mailboxes,  Next: Program Mailboxes,  Prev: Remote Mailboxes,  Up: Mailbox

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.


File: mailutils.info,  Node: Program Mailboxes,  Prev: SMTP Mailboxes,  Up: Mailbox

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 (*note 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.


File: mailutils.info,  Node: Programs,  Next: Libraries,  Prev: Mailbox,  Up: Top

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.

* Menu:

* command line::      Command Line Syntax.
* configuration::     Common Configuration File.
* debugging::

* frm and from::      List Headers from a Mailbox.
* mail::              Send and Receive Mail.
* messages::          Count the Number of Messages in a Mailbox.
* movemail::          Moves Mail from the User Maildrop to the Local File.
* readmsg::           Extract Messages from a Folder.
* decodemail::        Decode multipart messages.

* sieve::             Mail Filtering Utility.
* guimb::             Mailbox Scanning and Processing Language.

* mda::               Local Mail Delivery Agent.
* lmtpd::             LMTP Daemon.
* putmail::           Incorporate a Message to a Mailbox.

* mimeview::          Universal File Viewer.

* pop3d::             POP3 Daemon.
* imap4d::            IMAP4 Daemon.
* comsatd::           Comsat Daemon.

* mh::                The MH Message Handling System.

* mailutils::         The Mailutils Multi-Purpose Tool.
* dotlock::           The External Locker Utility.


File: mailutils.info,  Node: command line,  Next: configuration,  Up: Programs

3.1 Command Line
================

* Menu:

* Option Basics::       Basic Notions About Command Line Options.
* Common Options::      Options That are Common for All Utilities.


File: mailutils.info,  Node: Option Basics,  Next: Common Options,  Up: command line

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.


File: mailutils.info,  Node: Common Options,  Prev: Option Basics,  Up: command line

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.  *Note 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.  *Note the --set option::.


File: mailutils.info,  Node: configuration,  Next: debugging,  Prev: command line,  Up: Programs

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 *note Paths::.
For a detailed description of this option, *note the --set option::.

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

* Menu:

* conf-syntax::         Configuration File Syntax
* Variables::           Variable Expansion
* include::             Include Statement
* program statement::
* logging statement::
* debug statement::
* mailbox statement::
* mime statement::
* locking statement::
* mailer statement::
* acl statement::
* tcp-wrappers statement::
* Server Settings::
* auth statement::
* pam statement::
* virtdomain statement::
* radius statement::
* sql statement::
* ldap statement::
* tls statement::
* tls-file-checks statement::
* gsasl statement::


File: mailutils.info,  Node: conf-syntax,  Next: Variables,  Up: configuration

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.

* Menu:

* Comments::
* Statements::
* Paths::


File: mailutils.info,  Node: Comments,  Next: Statements,  Up: conf-syntax

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.


File: mailutils.info,  Node: Statements,  Next: Paths,  Prev: Comments,  Up: conf-syntax

3.2.1.2 Statements
..................

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

   The following is a simple statement:

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

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

   A "value" can be one of the following:

number
     A number is a sequence of decimal digits.

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

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

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

     Sequence               Replaced with
     \a                     Audible bell character (ASCII 7)
     \b                     Backspace character (ASCII 8)
     \f                     Form-feed character (ASCII 12)
     \n                     Newline character (ASCII 10)
     \r                     Carriage return character (ASCII
                            13)
     \t                     Horizontal tabulation character
                            (ASCII 9)
     \v                     Vertical tabulation character
                            (ASCII 11)
     \\                     A single backslash ('\')
     \"                     A double-quote.

     Table 3.1: Backslash escapes

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

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

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

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

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

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

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

          <<EOT
          A multiline
          string
          EOT

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

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

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

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

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

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

          alias (test,null);

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

          alias test;

     is equivalent to

          alias (test);

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

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

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


File: mailutils.info,  Node: Paths,  Prev: Statements,  Up: conf-syntax

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


File: mailutils.info,  Node: Variables,  Next: include,  Prev: conf-syntax,  Up: configuration

3.2.2 Configuration Variables
-----------------------------

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

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

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

${VARIABLE:-WORD}
     "Use Default Values".  If VARIABLE is unset or null, the expansion
     of WORD is substituted.  Otherwise, the value of VARIABLE is
     substituted.

${VARIABLE:=WORD}
     "Assign Default Values".  If VARIABLE is unset or null, the
     expansion of WORD is assigned to variable.  The value of VARIABLE
     is then substituted.

${VARIABLE:?WORD}
     "Display Error if Null or Unset".  If VARIABLE is null or unset,
     the expansion of WORD (or a message to that effect if WORD is not
     present) is output to the current logging channel.  Otherwise, the
     value of VARIABLE is substituted.

${VARIABLE:+WORD}
     "Use Alternate Value".  If VARIABLE is null or unset, nothing is
     substituted, otherwise the expansion of WORD is substituted.

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

     $(CMD ARG)

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

   The following commands are defined:

 -- Command: localpart STRING
     Treats STRING as an email address and returns the part preceding
     the '@' sign.  If there is no '@' sign, returns STRING.

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

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

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


File: mailutils.info,  Node: include,  Next: program statement,  Prev: Variables,  Up: configuration

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.


File: mailutils.info,  Node: program statement,  Next: logging statement,  Prev: include,  Up: configuration

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.


File: mailutils.info,  Node: logging statement,  Next: debug statement,  Prev: program statement,  Up: configuration

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 (*note 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'.


File: mailutils.info,  Node: debug statement,  Next: mailbox statement,  Prev: logging statement,  Up: configuration

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 *note 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.


File: mailutils.info,  Node: mailbox statement,  Next: mime statement,  Prev: debug statement,  Up: configuration

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 (*note Mailbox::), which may
     contain references to the 'user' variable (*note 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.17 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/'.


File: mailutils.info,  Node: mime statement,  Next: locking statement,  Prev: mailbox statement,  Up: configuration

3.2.8 The 'mime' Statement
--------------------------

Syntax
------

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

Description
-----------

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

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

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

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


File: mailutils.info,  Node: locking statement,  Next: mailer statement,  Prev: mime statement,  Up: configuration

3.2.9 The 'locking' Statement
-----------------------------

Syntax
------

     locking {
       # Default locker flags.
       type default | dotlock | external | kernel | null;

       # Set the maximum number of times to retry acquiring the lock.
       retry-count NUMBER;

       # Set the delay between two successive locking attempts.
       retry-sleep ARG;

       # Expire locks older than this amount of time.
       expire-timeout NUMBER;

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

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

Description
-----------

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

   It is important to note, that locking applies only to monolithic
mailboxes, i.e.  mailboxes of 'mbox' and 'dotmail' types (*note mbox::).
Other mailbox types don't require locking.

 -- Configuration: type STRING
     Set locking type.  Allowed arguments are:

     'default'
          Default locking type.  As of 'mailutils' version 3.17, this is
          equivalent to 'dotlock'.

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

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

          The locker program is invoked as follows:

               # To lock MBOX:
               LOCKER -fEXPIRE_TIMEOUT -rRETRY_COUNT MBOX
               # To unlock it:
               LOCKER -u -fEXPIRE_TIMEOUT -rRETRY_COUNT MBOX

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

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

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

          *Note dotlock::, for the description of the default external
          locker, shipped with mailutils.

     'kernel'
          Use kernel locking mechanism ('fcntl'(2)).

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

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

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

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

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

 -- Configuration: external-locker STRING
     Sets the name of the external locker program to use, instead of the
     default 'dotlock'.

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


File: mailutils.info,  Node: mailer statement,  Next: acl statement,  Prev: locking statement,  Up: configuration

3.2.10 The 'mailer' Statement
-----------------------------

Syntax
------

     mailer {
       url URL;
     }

Description
-----------

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

   The mailer statement contains a single sub-statement:

 -- Configuration: url STR
     Set the mailer URL.

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

smtp://[USER[:PASS][;auth=MECH,...]@]HOST[:PORT][;PARAMS]
smtps://[USER[:PASS][;auth=MECH,...]@]HOST[:PORT][;PARAMS]
     Send messages using SMTP protocol.  *Note 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.

     *Note sendmail: Program Mailboxes, 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 *note prog: Program Mailboxes.


File: mailutils.info,  Node: acl statement,  Next: tcp-wrappers statement,  Prev: mailer statement,  Up: configuration

3.2.11 The 'acl' Statement
--------------------------

Syntax
------

     acl {
       # Allow connections from this IP address.
       allow [from] IP;

       # Deny connections from this IP address.
       deny [from] IP;

       # Log connections from this IP address.
       log [from] IP [STRING];

       /* Execute supplied program if a connection from this
          IP address is requested. */
       exec [from] IP PROGRAM;

       /* Use PROGRAM to decide whether to allow connection
          from IP. */
       ifexec [from] IP PROGRAM;
     }

Description
-----------

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

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

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

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

   The following controls are understood:

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

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

 -- Configuration: ifexec [from] CIDR PROGRAM
     When a connection from the CIDR block is requested, execute the
     program PROGRAM.  If its exit code is '0', then allow connection.
     Otherwise, deny it.

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

     'aclno'
          Ordinal number of the control in the ACL. Numbers begin from
          '1'.

     'family'
          Connection family.  Mailutils version 3.17 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.


File: mailutils.info,  Node: tcp-wrappers statement,  Next: Server Settings,  Prev: acl statement,  Up: configuration

3.2.12 The 'tcp-wrappers' Statement
-----------------------------------

Syntax
------

     tcp-wrappers {
       # Enable TCP wrapper access control.
       enable BOOL;

       # Set daemon name for TCP wrapper lookups.
       daemon NAME;

       # Use FILE for positive client address access control.
       allow-table FILE;

       # Use file for negative client address access control.
       deny-table FILE;
     }

Description
-----------

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

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

   The description of a TCP wrapper table format lies outside the scope
of this document.  Please, see *note ACCESS CONTROL FILES:
(hosts_access(5))ACCESS CONTROL FILES, 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.


File: mailutils.info,  Node: Server Settings,  Next: auth statement,  Prev: tcp-wrappers statement,  Up: configuration

3.2.13 Server Settings
----------------------

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

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

* Menu:

* General Server Configuration::
* Server Statement::


File: mailutils.info,  Node: General Server Configuration,  Next: Server Statement,  Up: Server Settings

3.2.13.1 General Server Configuration
.....................................


Syntax:
     # Set daemon mode.
     mode 'inetd|daemon';

     # Run in foreground.
     foreground BOOL;

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

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

     # Default port number.
     port PORTSPEC;

     # Set idle timeout.
     timeout TIME;


   Description: These statements configure general server-related
issues.

 -- Configuration: mode STRING;
     Set operation mode of the server.  Two operation modes are
     supported:

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

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

     inetd
          Operate as a subprocess of UNIX internet super-server program,
          'inetd'.  *Note (inetd(8))Internet super-server::, for a
          detailed description of the operation of 'inetd' and its
          configuration.  In this case it is 'inetd' that controls all
          major connectivity aspects.  The Mailutils server 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.17, GNU Mailutils servers make no further use of this file.  It
     is intended for use by automated startup scripts and controlling
     programs (e.g.  *note GNU pies: (pies)Top.).

 -- 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' (*note (services(5))Internet network services
     list::).

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


File: mailutils.info,  Node: Server Statement,  Prev: General Server Configuration,  Up: Server Settings

3.2.13.2 The 'server' Statement
...............................


Syntax:
     server IPADDR[:PORT] {
       # Run this server as a single process.
       single-process BOOL;

       # Log the session transcript.
       transcript BOOL;

       # Set idle timeout.
       timeout TIME;

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

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

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

       # Set server specific ACLs.
       acl { /* *Note ACL Statement::. */ };
     }


   Description:

   The 'server' block statement configures a single TCP or UDP server.
It takes effect only in daemon mode (*note 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' (*note
(services(5))Internet network services list::).  If PORT is omitted,
Mailutils uses the port set by 'port' statement (*note port: General
Server Configuration.), 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 (*note timeout: General Server Configuration.).

 -- Configuration: backlog NUMBER;
     Configures the size of the queue of pending connections

 -- Configuration: tls-mode MODE;
     Configure the use of TLS encryption.  The MODE argument is one of
     the following:

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

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

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

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

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

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

     *Note tls statement::, for a discussion of its syntax.

 -- Configuration: acl
     This statement defines a per-server Access Control List.  Its
     syntax is as described in *note 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.


File: mailutils.info,  Node: auth statement,  Next: pam statement,  Prev: Server Settings,  Up: configuration

3.2.14 The 'auth' Statement
---------------------------

Syntax
------

     auth {
       # Set a list of modules for authentication.
       authentication MODULE-LIST;

       # Set a list of modules for authorization.
       authorization MODULE-LIST;
     }

Description
-----------

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

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

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

   For example, the authorization list

       (system, sql, virtdomains)

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

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

   The 'auth' statement configures authentication and authorization.

 -- Configuration: authorization MODULE-LIST
     Define a sequence of modules to use for authorization.  Modules
     will be tried in the same order as listed in MODULE-LIST.

     The modules available for use in authorization list are:

     system
          User credentials are retrieved from the system user database
          ('/etc/password').
     sql
          User credentials are retrieved from a SQL database.  A
          separate configuration statement, 'sql', is used to configure
          it (*note sql statement::).
     virtdomain
          User credentials are retrieved from a "virtual domain" user
          database.  Virtual domains are configured using 'virtdomain'
          statement (*note virtdomain statement::).
     radius
          User credentials are retrieved using RADIUS.  *Note radius
          statement::, for a detailed description on how to configure
          it.
     ldap
          User credentials are retrieved from an LDAP database.  *Note
          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 (*note
          getpass: sql statement.).
     pam
          The user is authenticated via pluggable authentication module
          (PAM).  The PAM service name to be used is configured in 'pam'
          statement (*note pam statement::).
     radius
          The user is authenticated on a remote RADIUS server.  *Note
          radius statement::.
     ldap
          The user is authenticated using LDAP.  *Note 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


File: mailutils.info,  Node: pam statement,  Next: virtdomain statement,  Prev: auth statement,  Up: configuration

3.2.15 PAM Statement
--------------------

Syntax
------

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

Description
-----------

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

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

   This statement takes effect only if 'pam' is listed in
'authentication' statement (*note auth statement::).


File: mailutils.info,  Node: virtdomain statement,  Next: radius statement,  Prev: pam statement,  Up: configuration

3.2.16 The 'virtdomain' Statement
---------------------------------

Syntax
------

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

Description
-----------

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

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

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

   For example, when authenticating user 'smith@example.com', the server
will use password file named 'DIR/example.com'.  This file must be in
UNIX passwd format (*note (passwd(5))password file::), with encrypted
passwords stored in it (as of GNU Mailutils version 3.17, 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.


File: mailutils.info,  Node: radius statement,  Next: sql statement,  Prev: virtdomain statement,  Up: configuration

3.2.17 The 'radius' Statement
-----------------------------

Syntax
------

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

Description
-----------

The 'radius' block statement configures RADIUS authentication and
authorization.

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

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

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

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

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

     $INCLUDE dict/mailutils.dict

   Requests to use for authentication and authorization are configured
using three statements: 'auth', 'getpwnam' and 'getpwuid'.  Each
statement takes a single argument: a string, containing a
comma-separated list of assignments.  An assignment specifies a
particular "attribute-value pair" (*note RADIUS Attributes:
(radius)Overview.) to send to the server.  The left-hand side of the
assignment is a symbolic attribute name, as defined in one of Radius
dictionaries (*note Dictionary of Attributes: (radius)dictionary file.).
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
(*note 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' (*note Access-Accept: (radius)Authentication
     Requests.).  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
     (*note URL: Mailbox.).  If 'GNU-MU-Mailbox' is not present,
     Mailutils constructs the mailbox name using the settings from the
     'mailbox' configuration statement (*note 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).


File: mailutils.info,  Node: sql statement,  Next: ldap statement,  Prev: radius statement,  Up: configuration

3.2.18 The 'sql' Statement
--------------------------

Syntax
------

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

Description
-----------

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

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

 -- Configuration: interface TYPE
     Configures type of DBMS interface.  Allowed values for TYPE are:

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

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

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

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

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

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

 -- Configuration: db ARG;
     Name of the database.

 -- Configuration: user ARG
     SQL user name.

 -- Configuration: passwd ARG;
     Password to access the database.

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

     plain
          Password is in plain text.

     crypt
     hash
          Password is encrypted by system 'crypt' function (*note
          (crypt(3))crypt::).

     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 (*note 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 (*note
          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 (*note 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 (*note 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 *note 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.


File: mailutils.info,  Node: ldap statement,  Next: tls statement,  Prev: sql statement,  Up: configuration

3.2.19 The 'ldap' Statement
---------------------------

Syntax
------

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

Description
-----------

The 'ldap' statement configures the use of LDAP for authentication.

 -- Configuration: enable BOOL
     Enables LDAP lookups.  If absent, 'enable On' is assumed.

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

 -- Configuration: base STRING
     Defines base DN for LDAP lookups.

 -- Configuration: binddn STRING
     Defines the DN for accessing LDAP database.

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

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

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

 -- Configuration: field-map MAP
     Defines a map for parsing LDAP replies.  The MAP is a list of
     mappings(1).  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))

   ---------- Footnotes ----------

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


File: mailutils.info,  Node: tls statement,  Next: tls-file-checks statement,  Prev: ldap statement,  Up: configuration

3.2.20 The 'tls' Statement
--------------------------

Syntax
------

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

Description
-----------

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

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

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

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

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

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


File: mailutils.info,  Node: tls-file-checks statement,  Next: gsasl statement,  Prev: tls statement,  Up: configuration

3.2.21 The 'tls-file-checks' Statement
--------------------------------------

Syntax
------

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

Description
-----------

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

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

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

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

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


File: mailutils.info,  Node: gsasl statement,  Prev: tls-file-checks statement,  Up: configuration

3.2.22 The 'gsasl' Statement
----------------------------

  ==================================================================
                           *Editor's note:*
     This node is to be written.
  ==================================================================

Syntax
------

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


File: mailutils.info,  Node: debugging,  Next: frm and from,  Prev: configuration,  Up: Programs

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.

* Menu:

* Level Syntax::
* Level BNF::
* Debugging Categories::


File: mailutils.info,  Node: Level Syntax,  Next: Level BNF,  Up: debugging

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


File: mailutils.info,  Node: Level BNF,  Next: Debugging Categories,  Prev: Level Syntax,  Up: debugging

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"


File: mailutils.info,  Node: Debugging Categories,  Prev: Level BNF,  Up: debugging

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

server
     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


File: mailutils.info,  Node: frm and from,  Next: mail,  Prev: debugging,  Up: Programs

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:

Statement              Reference
-------------------------------------------------------------------
debug                  *Note debug statement::.
tls                    *Note tls statement::.
mailbox                *Note mailbox statement::.
locking                *Note 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 with 'From:' header containing the supplied
     string.

'-f URL'
'--file=URL'
     Examine mailbox from the given URL.


File: mailutils.info,  Node: mail,  Next: messages,  Prev: frm and from,  Up: Programs

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 POSIX 'mailx' program.  The program
operates in two modes: "read" and "send".

   'Mail' enters "send" mode when at least one email address was
specified in its command line.  In this mode the program waits until
user finishes composing the message, then attempts to send it to the
specified addresses and exits.  *Note Composing Mail::, for a detailed
description of this behavior.

   If the command line contained no email addresses, 'mail' switches to
reading mode.  In this mode it allows the user to read and manipulate
the contents of the user system mailbox.  Use the '--file' ('-f') option
to specify another mailbox name.  For more detail, see *note Reading
Mail::.

   In addition to the Mailutils configuration file, 'mail' reads the
traditional 'mailrc'-style configuration files.  *Note Mail
Configuration Files::, for a detailed description of their format.

* Menu:

* Invoking Mail::            Command Line Options.
* Reading Mail::             Reading Mail.
* Saving and Recording::     Where Mail Messages are Stored.
* Composing Mail::           Composing Mail.
* MIME::                     How to Attach Files.
* Scripting::                Scripting.
* Mail Variables::           How to Alter the Behavior of 'mail'.
* Mail Configuration Files:: Personal and System-wide Configuration Files.


File: mailutils.info,  Node: Invoking Mail,  Next: Reading Mail,  Up: mail

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, content type,
     and content description are controlled by the '--encoding',
     '--content-type', and '--content-name' options, correspondingly.

     The option '--attach=-' instructs 'mail' to read the file to be
     attached from the standard input.  Interactive shell is disabled in
     this case.

'--attach-fd=FD'
     Read attachment body from the file descriptor FD.  The descriptor
     must be open for reading.  This option is useful when calling
     'mail' from another program.

     See the options '--encoding', '--content-type', '--content-name',
     and '--content-filename'.

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

'--content-filename=NAME'
     Set the 'filename' parameter in the 'Content-Disposition' header
     for the next '--attach-fd' option.

'--content-name=TEXT'
     Set the 'name' parameter (description) in the 'Content-Type' header
     for the next '--attach' or '--attach-fd' option.

'-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 (*note 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.

'-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.  *Note 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.

'-M'
'--mime'
'--no-mime'
     The '--mime' option instructs 'mail' to compose MIME messages.  It
     is equivalent for '-E 'set mime'', except that it is processed
     after all other options.  The '--no-mime' disables the MIME compose
     mode, and is a shortcut for '-E 'set nomime'',

'-N'
'--nosum'
     Do not display initial header summary.

'-n'
'--norc'
     Do not read the system-wide mailrc file.  *Note 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.  *Note
     return-address::.

'--skip-empty-attachments'
'--no-skip-empty-attachments'
     Don't create attachments that would have zero-size body.  This
     option affects all attachments created by '--attach' and
     '--attach-fd' options appearing after it in the command line, as
     well as the body of the original message.

     To cancel its effect, use the '--no-skip-empty-attachments' option.

'-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 (*note
Common Options::.


File: mailutils.info,  Node: Reading Mail,  Next: Saving and Recording,  Prev: Invoking Mail,  Up: mail

3.5.2 Reading Mail
------------------

The 'mail' utility operates on three kinds of mailboxes.  The "user
system mailbox" is the mailbox where the incoming mail for the user is
stored.  Its location is system-dependent and is determined using the
common mailutils rules (*note mailbox statement::).  The "personal
mailbox" (or "mbox", for short) is the default location for saving
messages that have been read.  By default it is '$HOME/mbox' or whatever
file specified by the 'MBOX' environment variable.  Any other mailboxes
are called "secondary mailboxes".

   When called without arguments, 'mail' opens the system mailbox for
the invoking user.  The '--file' ('-f') used without arguments instructs
'mail' to operate on the personal mailbox instead.  When this option and
a single command line argument are used together, 'mail' treats the
argument as the pathname of the secondary mailbox to operate upon.

   Notice that this argument is not an argument to the '--file' ('-f')
option itself, but rather the first non-optional argument on the command
line.  This means that any number of additional options are allowed
between the '--file' option and the mailbox file name.  For example, the
following three invocations are equivalent:

     $ mail -fin mymbox
     $ mail -f mymbox -in
     $ mail --file -in mymbox
     $ mail --file -i mymbox -n

   Additionally, for conformance to the GNU standards, the following
form is also accepted:

     $ mail --file=mymbox -i -n

   The '--user' ('-u') option allows the system administrator to assume
another user identity for operating on this user's mailboxes.
Obviously, it is available only to system administrators.  For example:

     mail --user=tom

reads mail from the system mailbox of the user 'tom', and

     mail --user=tom --file

reads mail from the personal mailbox of this user.

   Unless you have started mail with '--norc' command line option, it
will read the contents of the system-wide configuration file.  Then it
will read the contents of user configuration file, if it exists.  For
detailed description of these files, see *note Mail Configuration
Files::.  After this initial setup, 'mail' displays the first page of
header lines (unless the '-N' option has been given), followed by a
prompt, indicating that it is waiting for regular commands.  Upon
receiving a command, 'mail' parses and executes it, displays the result
on the screen, prints the prompt and waits for the next command.  This
process is continued until 'mail' receives any of the commands 'quit',
'exit' or the end-of-file character (ASCII 4, or 'C-D').

   Each message in the mailbox has a state that affects how it is
retained or deleted upon closing the mailbox when terminating the
program (*note the quit command::) or when switching to another mailbox
(*note the file command::).  The state is reflected in the header
listing and can be changed during the session.  The states are:

"new"
     The message is present in the system mailbox and has not been read
     by the user or moved to any other state.  When 'mail' terminates,
     messages in this state are retained in the system mailbox.  If the
     mailbox is closed, such messages are moved to the 'unread' state.

"unread"
     The message has been present in the system mailbox for more than
     one invocation of 'mail' and has not been read by the user or moved
     to any other state.  When 'mail' terminates, messages in this state
     are retained in the system mailbox.

"read"
     The message has been read by the user, i.e.  processed by one of
     the following commands: 'copy', 'mbox', 'next', 'pipe', 'prev',
     'print', 'Print', 'struct', 'top', 'type', 'Type', 'undelete', or
     any of the following escapes (in message compose mode): '~f', '~m',
     '~F', '~M'.

     When 'mail' terminates, messages in this state are handled
     depending on the mailbox they are in.

     If 'mail' was operating on the user system mailbox, all messages in
     state 'read' are preserved.  The location where they are preserved
     is determined by the 'hold' variable (*note Mail Variables::).  If
     it is not set (the default), the messages are moved to the user's
     'mbox'.  If 'hold' is set, the messages are held in the system
     mailbox instead.

     The 'read' messages in any other mailbox will be retained in their
     current location.

"deleted"
     The message has been processed by one of the following commands:
     'delete', 'dp', 'dt'.  Messages in this state are ignored by any
     command, excepting 'undelete', which changes their state back to
     'read'.  When closing the mailbox, deleted messages are permanently
     removed from the mailbox.

"preserved"
     The message has been processed by the 'preserve' ('hold') command.
     When closing the mailbox, such messages are retained in the
     mailbox.

"saved"
     The message has been processed by one of the following commands:
     'save', 'write'.  When 'mail' terminates, messages in this state
     are handled depending on the mailbox they are in.

     If 'mail' was operating on the user system mailbox, the default
     behavior for 'saved' messages is to remove them from the system
     mailbox.  If, however, the 'keepsave' variable is set, they are
     preserved using the same rules as for 'read' messages (see above).

     Saved messages in non-system mailboxes are retained in their
     current location.

   Unless the mailbox is empty, exactly one of its messages will be
marked as "current message".  Upon startup, current message is set to
the first new message, if there is any, or the first unread message if
there is any, or to the first message in the mailbox.  In the header
listing, current message is marked with the '>' sign at the beginning of
the line.  Current message is changed by any of the following commands:
'dp', 'prev', 'next'.

* Menu:

* Command Syntax::           Syntax of mail internal commands.
* Quitting the Program::
* Obtaining Online Help::
* Moving Within a Mailbox::
* Changing mailbox/directory::
* Controlling Header Display::
* Displaying Information::
* Displaying Messages::
* Marking Messages::
* Disposing of Messages::
* Saving Messages::
* Editing Messages::
* Aliasing::
* Replying::
* Controlling Sender Fields::
* Incorporating New Mail::
* Shell Escapes::


File: mailutils.info,  Node: Command Syntax,  Next: Quitting the Program,  Up: Reading Mail

3.5.2.1 Syntax of mail internal commands
........................................

Commands have the following syntax:

     COMMAND [MSGLIST] [ARGUMENT ...]

   A command is terminated by a newline character.  Empty command (i.e.
a newline character alone) is equivalent to 'next' (*note next: Moving
Within a Mailbox.).

   In the syntax above, COMMAND is the command verb.  Each command has
long and short (abbreviated) form.  Each of them can be used to invoke
the command.

   Many mail commands take a list of messages (MSGLIST) to operate upon,
which defaults to current message.

   The list of messages in its simplest form is one of:

.              Selects current message.  It is equivalent to
               empty message list.
*              Selects all messages in the mailbox.
^              Selects first non-deleted message.
$              Selects last non-deleted message.

   In its complex form, the "message list" is a comma or
whitespace-separated list of "message specifiers".  A "message
specifier" is one of

N
     (integer number) This specifier addresses the message with the
     given ordinal number in the mailbox.

N-M
     All messages with ordinal numbers between N and M, inclusive.

:T
     All messages of type T, where T can be any of:

     'd'
          Deleted messages.
     'n'
          New messages.
     'o'
          Old messages (any message not in state 'read' or 'new').
     'r'
          Messages in state 'read'.
     'u'
          Messages in state 'unread'.
     't'
          Selects all tagged messages.
     'T'
          Selects all untagged messages.
     's'
          Selects all messages in state 'saved'.

[HEADER:]/STRING[/]
     Header match.

     Selects all messages that contain header field HEADER matching
     given STRING.  If the variable 'regex' is set, the STRING is
     assumed to be a POSIX regexp.  (All comparison is case-insensitive
     in either case).

     If HEADER: part is omitted, it is assumed to be 'Subject:'.

:/STRING[/]
     Message body match.

     Selects all messages with body matching the STRING.  The matching
     rules are the same as described above.

   Some 'mail' commands can operate on parts of multipart messages.  In
arguments to such commands, a message part is indicated by suffixing the
message specifier by a dot and the number of that part in the message
(message parts, as well as messages, are indexed from 1).  For example,
the command

     write 4.1

will operate on part 1 of the message 4.  Message parts can in turn be
multipart messages.  Such nested subparts are indicated in a similar
manner, for example:

     write 4.1.2

which means subpart 2 of the part 1 of message 4.(1)

   The following are the examples of valid message lists:

3
     Third message.

1-4 10
     Messages from 1 through 4 and message 10.

4-*
     All messages starting from message 4.

/watch
     All messages with the word 'watch' in the subject.

/watch :/watch
     All messages with the word 'watch' in the subject or body.

/watch :/watch $
     Same as above plus the last message in the mailbox.

10.2
     Part 2 of the multipart message 10.

   ---------- Footnotes ----------

   (1) For compatibility with earlier versions of 'mailutils', a message
part can also be specified as a list of numbers enclosed in a pair of
brackets, such as '4[2]', instead of '4.2'.  This syntax is deprecated
and will be withdrawn from future releases.


File: mailutils.info,  Node: Quitting the Program,  Next: Obtaining Online Help,  Prev: Command Syntax,  Up: Reading Mail

3.5.2.2 Quitting the Program
............................

Following commands quit the program:

 -- Mail command: quit
     Terminates the session.  The messages, marked with 'delete' are
     removed.  The messages in state 'read' and 'saved' are processed
     depending on the mailbox they are in.

     If 'mail' was operating on the user system mailbox, all messages in
     state 'read' are preserved.  The location where they are preserved
     is determined by the 'hold' variable.  If it is not set (the
     default), the messages are moved to the user's 'mbox'.  If 'hold'
     is set, the messages are held in the system mailbox instead.

     The default behavior for 'saved' messages is to remove them from
     the system mailbox.  If, however, the 'keepsave' variable is set,
     they are preserved using the same rules as for 'read' messages.

     For non-system mailboxes, both 'read' and 'saved' messages are
     retained in their current location.

     The same rules are followed when the mailbox is switched using the
     'file' command.

     The program exits to the shell, unless saving the mailbox fails, in
     which case user can escape with the exit command.

 -- Mail command: exit
 -- Mail command: ex
 -- Mail command: xit
     Program exits to the shell without modifying the mailbox it
     operates upon.

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


File: mailutils.info,  Node: Obtaining Online Help,  Next: Moving Within a Mailbox,  Prev: Quitting the Program,  Up: Reading Mail

3.5.2.3 Obtaining Online Help
.............................

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

 -- Mail command: help [COMMAND]
 -- Mail command: hel [COMMAND]
 -- Mail command: ? [COMMAND]
     Display detailed command synopsis.  If no COMMAND is given, help
     for all available commands is displayed.

 -- Mail command: list
 -- Mail command: *
     Print a list of available commands.

 -- Mail command: version
 -- Mail command: ve
     Display program version.

 -- Mail command: warranty
 -- Mail command: wa
     Display program warranty statement.


File: mailutils.info,  Node: Moving Within a Mailbox,  Next: Changing mailbox/directory,  Prev: Obtaining Online Help,  Up: Reading Mail

3.5.2.4 Moving Within a Mailbox
...............................

 -- Mail command: ^
     Move to the first undeleted message.

 -- Mail command: $
     Move to the last undeleted message.

 -- Mail command: next
 -- Mail command: n
     Move to the next message.

 -- Mail command: previous
 -- Mail command: prev
     Move to the previous message.


File: mailutils.info,  Node: Changing mailbox/directory,  Next: Controlling Header Display,  Prev: Moving Within a Mailbox,  Up: Reading Mail

3.5.2.5 Changing Mailbox/Directory
..................................

 -- Mail command: cd [DIR]
 -- Mail command: chdir [DIR]
 -- Mail command: ch [DIR]
     Change to the specified directory.  If DIR is omitted, '$HOME' is
     assumed.

 -- Mail command: file [MAILBOX]
 -- Mail command: fi [MAILBOX]
 -- Mail command: folder [MAILBOX]
 -- Mail command: fold [MAILBOX]
     When used without argument, prints the information about the
     current mailbox: the mailbox file name (or URL), total number of
     messages and the number of unread messages, e.g.:

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

     Otherwise, closes the current mailbox and opens the mailbox named
     by the MAILBOX argument.  When closing the current mailbox, its
     messages are processed according to their state (*note mail message
     states::).

     The MAILBOX argument can be the name of the existing file, a
     mailbox URL (*note Mailbox::), or any of the following shortcuts:

     %
          The system mailbox for the invoking user.

     %USER
          The system mailbox for USER.

     #
          The previous file.

     &
          The user's personal mailbox.

     @
          Secondary mailbox, given using the '-f' command line option.

     +FILE
          The named FILE in the folder directory.  *Note folder
          variable::.


File: mailutils.info,  Node: Controlling Header Display,  Next: Displaying Information,  Prev: Changing mailbox/directory,  Up: Reading Mail

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

 -- Mail command: discard [HEADER-FIELD-LIST]
 -- Mail command: di [HEADER-FIELD-LIST]
 -- Mail command: ignore [HEADER-FIELD-LIST]
 -- Mail command: ig [HEADER-FIELD-LIST]
     Add HEADER-FIELD-LIST to the ignored list.  When used without
     arguments, this command prints the contents of ignored list.

 -- Mail command: retain [HEADER-FIELD-LIST]
 -- Mail command: ret [HEADER-FIELD-LIST]
     Add HEADER-FIELD-LIST to the retained list.  When used without
     arguments, this command prints the contents of retained list.


File: mailutils.info,  Node: Displaying Information,  Next: Displaying Messages,  Prev: Controlling Header Display,  Up: Reading Mail

3.5.2.7 Displaying Information
..............................

 -- Mail command: =
     Displays the current message number.

 -- Mail command: headers [MSGLIST]
 -- Mail command: h [MSGLIST]
     Lists the current pageful of headers.

 -- Mail command: from [MSGLIST]
 -- Mail command: f [MSGLIST]
     Lists the contents of 'From' headers for a given set of messages.

 -- Mail command: 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.

 -- Mail command: size [MSGLIST]
 -- Mail command: si [MSGLIST]
     Lists the message number and message size in bytes for each message
     in MSGLIST.

 -- Mail command: folders
     Displays the value of 'folder' variable.

 -- Mail command: summary
 -- Mail command: su
     Displays current mailbox summary.  E.g.:

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


File: mailutils.info,  Node: Displaying Messages,  Next: Marking Messages,  Prev: Displaying Information,  Up: Reading Mail

3.5.2.8 Displaying Messages
...........................

 -- Mail command: print [MSGLIST]
 -- Mail command: p [MSGLIST]
 -- Mail command: type [MSGLIST]
 -- Mail command: 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.

 -- Mail command: Print [MSGLIST]
 -- Mail command: P [MSGLIST]
 -- Mail command: Type [MSGLIST]
 -- Mail command: T [MSGLIST]
     Like print but also prints out ignored header fields.

 -- Mail command: decode [MSGLIST]
 -- Mail command: dec [MSGLIST]
     Print a multipart message.  The 'decode' command decodes and prints
     out specified messages.  The MSGLIST can contain message parts
     (*note message part specification::), in which case only specified
     message parts will be output.

          ? decode 15.2
          +---------------------------------------
          | Message=15.2
          | Type=message/delivery-status
          | encoding=7bit
          +---------------------------------------
          Content-Type: message/delivery-status
          ...

 -- Mail command: top [MSGLIST]
 -- Mail command: 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.

 -- Mail command: pipe [[MSGLIST] SHELL-COMMAND]
 -- Mail command: | [[MSGLIST] SHELL-COMMAND]
     Pipe the contents of specified messages through SHELL-COMMAND.
     Without arguments, pipe the current message through the command
     given by the 'cmd' variable (which must be set).

 -- Mail command: 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


File: mailutils.info,  Node: Marking Messages,  Next: Disposing of Messages,  Prev: Displaying Messages,  Up: Reading Mail

3.5.2.9 Marking Messages
........................

 -- Mail command: tag [MSGLIST]
 -- Mail command: ta [MSGLIST]
     Tag messages.  The tagged messages can be referred to in message
     list using ':t' notation.

 -- Mail command: untag [MSGLIST]
 -- Mail command: unt [MSGLIST]
     Clear tags from specified messages.  To untag all messages tagged
     so far type
          ? untag :t

 -- Mail command: hold [MSGLIST]
 -- Mail command: ho [MSGLIST]
 -- Mail command: preserve [MSGLIST]
 -- Mail command: pre [MSGLIST]
     Marks each message to be held in user's system mailbox.  This
     command does not override the effect of 'delete' command.

 -- Mail command: unread [MSGLIST]
     Marks each message from the MSGLIST as not having been read.


File: mailutils.info,  Node: Disposing of Messages,  Next: Saving Messages,  Prev: Marking Messages,  Up: Reading Mail

3.5.2.10 Disposing of Messages
..............................

 -- Mail command: delete [MSGLIST]
 -- Mail command: 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.

 -- Mail command: undelete [MSGLIST]
 -- Mail command: u [MSGLIST]
     Clear delete mark from the specified messages.

 -- Mail command: dp [MSGLIST]
 -- Mail command: 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.


File: mailutils.info,  Node: Saving Messages,  Next: Editing Messages,  Prev: Disposing of Messages,  Up: Reading Mail

3.5.2.11 Saving Messages
........................

 -- Mail command: save [[MSGLIST] MAILBOX]
 -- Mail command: s [[MSGLIST] MAILBOX]
     Takes a message list and a file or mailbox name and appends each
     message in turn to that file or mailbox.  The syntax for MAILBOX is
     the same as for the 'file' command (*note Mailbox shortcuts::).
     The name of the mailbox and number of lines and characters appended
     to it is echoed on the terminal.  When writing to file, the numbers
     represent exact number of lines and characters appended to the
     file.  When FILE specifies a mailbox, these numbers may differ by
     the amount of lines/characters needed to represent message envelope
     for that specific mailbox type.

     Each saved message is marked for deletion as if with 'delete'
     command, unless the variable 'keepsave' is set.

 -- Mail command: Save [MSGLIST]
 -- Mail command: S [MSGLIST]
     Like 'save', but the file to append messages to is named after the
     sender of the first message in MSGLIST.  The file name is selected
     as described in *note saving mail by name::.  For example:

          ? from 14 15
           U  14 smith@noldor.org Fri Jun 30 18:11  14/358   The Save c
           U  15 gray@noldor.org  Fri Jun 30 18:30  8/245    Re: The Sa
          ? Save 14 15
          "smith" 22/603

     i.e., 22 lines (603 characters) have been appended to the file
     "smith".  If the file does not exist, it is created.

 -- Mail command: write [[MSGLIST] FILE]
 -- Mail command: w [[MSGLIST] FILE]
     Similar to 'save', except that only message body (without the
     header) is saved.  The MSGLIST can contain message parts (*note
     message part specification::), in which case only specified message
     parts will be saved.

 -- Mail command: Write [MSGLIST]
 -- Mail command: W [MSGLIST]
     Similar to 'Save', except that only message body (without the
     header) is saved.  The MSGLIST can contain message parts (*note
     message part specification::), in which case only specified message
     parts will be saved.

 -- Mail command: mbox [MSGLIST]
 -- Mail command: mb [MSGLIST]
     Mark list of messages to be saved in the user's personal mailbox
     (*note personal mailbox: Reading Mail.) upon exiting via 'quit'
     command.  This is the default action for all read messages, unless
     you have variable 'hold' set.

 -- Mail command: touch [MSGLIST]
 -- Mail command: tou [MSGLIST]
     Touch the specified messages.  If any message in MSGLIST is not
     specifically deleted nor saved in a file, upon normal termination
     it will be acted upon as if it had been read (*note mail message
     states::).

 -- Mail command: copy [[MSGLIST] FILE]
 -- Mail command: c [[MSGLIST] FILE]
     Similar to 'save', except that saved messages are not marked as
     saved.

 -- Mail command: Copy [MSGLIST]
 -- Mail command: C [MSGLIST]
     Similar to 'Save', except that saved messages are not marked as
     saved.


File: mailutils.info,  Node: Editing Messages,  Next: Aliasing,  Prev: Saving Messages,  Up: Reading Mail

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

 -- Mail command: edit [MSGLIST]
 -- Mail command: e [MSGLIST]
     Edits each message in MSGLIST with the editor, specified in
     'EDITOR' environment variable.

 -- Mail command: visual [MSGLIST]
 -- Mail command: v [MSGLIST]
     Edits each message in MSGLIST with the editor, specified in
     'VISUAL' environment variable.


File: mailutils.info,  Node: Aliasing,  Next: Replying,  Prev: Editing Messages,  Up: Reading Mail

3.5.2.13 Aliasing
.................

 -- Mail command: alias [alias [ADDRESS...]]
 -- Mail command: a [alias [ADDRESS...]]
 -- Mail command: group [alias [ADDRESS...]]
 -- Mail command: 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.

 -- Mail command: unalias [ALIAS...]
 -- Mail command: 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.

 -- Mail command: alternates NAME...
 -- Mail command: 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.


File: mailutils.info,  Node: Replying,  Next: Controlling Sender Fields,  Prev: Aliasing,  Up: Reading Mail

3.5.2.14 Replying
.................

 -- Mail command: mail [ADDRESS...]
 -- Mail command: m [ADDRESS...]
     Switches to compose mode.  After composing the message, sends it to
     the specified addresses.

     If the 'record' variable is set, the composed message will be saved
     in the folder named by it.

 -- Mail command: Mail [ADDRESS...]
 -- Mail command: M [ADDRESS...]
     Same as 'mail', but the name of the file to save the composed
     message is derived from its first recipient as outlined below.

     If the 'outfolder' variable is set, and has a string value S, the
     filename is 'S/RECIPIENT'.  If it is a boolean, then the 'folder'
     variable is consulted.  If it is set, then the filename is
     'FOLDER/RECIPIENT'.  Otherwise, the message will not be saved.

     The value RECIPIENT is derived from the email of the first
     recipient of the message.  By default it is a local part of that
     email.  If the 'outfilename' variable has the value 'domain', the
     domain part of the email is used.  If this variable is set to
     'email', then entire email address is used.

     *Note saving mail by name::, for a detailed discussion.

 -- Mail command: reply [MESSAGE]
 -- Mail command: respond [MESSAGE]
 -- Mail command: r [MESSAGE]
     Mail a reply message to all recipients included in the header of
     the MESSAGE.  The subject header is formed by concatenating the
     value of the 'replyprefix' variable and the subject from the
     message.  If 'record' is set to a filename, the response is saved
     at the end of that file.

 -- Mail command: Reply [MSGLIST]
 -- Mail command: Respond [MSGLIST]
 -- Mail command: R [MSGLIST]
     Mail a reply message to the sender of each message in the MSGLIST.
     The subject header is formed by concatenating the value of the
     'replyprefix' variable and the subject header of from the first
     message in MSGLIST.  If 'record' is set to a filename, the response
     is saved at the end of that file.

     Notice, that setting mail variable 'flipr' (*note Mail Variables::)
     swaps the meanings of the two above commands

 -- Mail command: followup [MESSAGE]
 -- Mail command: fo [MESSAGE]
     Respond to MESSAGE, recording the response in a file whose name is
     derived from the author of the message.  *Note saving mail by
     name::, for a discussion of how the file name is selected.

 -- Mail command: Followup [MSGLIST]
 -- Mail command: F [MSGLIST]
     Same as 'Reply', but the response is saved in a file whose name is
     derived from the author of the first message.  *Note saving mail by
     name::, for a detailed discussion of how the file name is selected.

   By default, 'mail' will preserve personal email parts when forming
lists of recipient addresses.  If this is not desired, unset the
'fullnames' variable (*note fullnames::).

   To determine the sender of the message 'mail' uses the list of sender
fields (*note 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



File: mailutils.info,  Node: Controlling Sender Fields,  Next: Incorporating New Mail,  Prev: Replying,  Up: Reading Mail

3.5.2.15 Controlling Sender Fields
..................................

When 'mail' needs to know the sender of a message, it looks it up in one
or more headers of that message.  Such headers constitute a "sender
list".  The first header from the list that is present in the message
and has a non-empty value is used.  If none is found or if the sender
list is empty, the value of the message envelope is used.

   The commands 'sender' and 'nosender' manipulate the sender list.

   If the command 'sender' is used without arguments, it displays the
contents of the sender field list.  If arguments are given, each
argument is appended to the sender field list.  For example:

     ? sender
     Sender address is obtained from the envelope
     ? sender mail-followup-to reply-to
     ? sender
     mail-followup-to
     reply-to
     ? sender from
     ? sender
     mail-followup-to
     reply-to
     from

   Command 'nosender' is used to remove items from the sender field
list:

     ? sender
     mail-followup-to
     reply-to
     from
     ? nosender reply-to
     ? sender
     mail-followup-to
     from

   When used without arguments, this command clears the list:

     ? nosender
     Sender address is obtained from the envelope


File: mailutils.info,  Node: Incorporating New Mail,  Next: Shell Escapes,  Prev: Controlling Sender Fields,  Up: Reading Mail

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


File: mailutils.info,  Node: Shell Escapes,  Prev: Incorporating New Mail,  Up: Reading Mail

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


File: mailutils.info,  Node: Saving and Recording,  Next: Composing Mail,  Prev: Reading Mail,  Up: mail

3.5.3 Saving and Recording
--------------------------

Several commands discussed in the previous section save messages in a
disk file.  The name of that file is either obtained from the 'record'
variable ("recording mail") or is derived from the first recipient of
the message ("saving by name").

   The following commands record mails:

   * 'mail'
   * 'reply'
   * 'Reply'

   The following commands save mail by name:

   * 'Copy'
   * 'Save'
   * 'Mail'
   * 'followup'
   * 'Followup'

   Saving mail by name is controlled by three mail variables:
'outfolder', 'folder', and 'outfilename'.  The first, 'outfolder', is a
boolean variable which, when set, enables saving mail by name.  The
'folder' variable defines a directory where mail files are stored.  Name
of file in that directory where the message will be saved is derived
from the message recipient(1).  This process is controlled by the
'outfilename' variable: if its value is 'local', the file is named by
the local part of the email (this is the default).  If it is 'domain',
the domain part is used instead.  Finally, if it's value is 'email', the
entire email is used.

   As a GNU extension, 'outfolder' can be a string variable.  In that
case its value names the directory to use instead of 'folder'.

   The 'mailx' variable, if set, disables GNU extensions.  In this case,
'outfolder' is used as a boolean value, and file names are derived from
the local part of the email, ignoring the 'outfilename' value.

   ---------- Footnotes ----------

   (1) In case of 'Copy' and 'Save', message sender is used instead


File: mailutils.info,  Node: Composing Mail,  Next: MIME,  Prev: Saving and Recording,  Up: mail

3.5.4 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 and the standard
input is connected to a terminal.  If the escape character must appear
at the beginning of a line, enter it twice.

   The actual escape character may be changed by setting the value of
'escape' mail variable (*note Mail Variables::).

* Menu:

* Quitting Compose Mode::
* Getting Help on Compose Escapes::
* Editing the Message::
* Modifying the Headers::
* Enclosing Another Message::
* Adding a File to the Message::
* Attaching a File to the Message::
* Printing And Saving the Message::
* Signing the Message::
* Printing Another Message::
* Inserting Value of a Mail Variable::
* Executing Other Mail Commands::
* Executing Shell Commands::


File: mailutils.info,  Node: Quitting Compose Mode,  Next: Getting Help on Compose Escapes,  Up: Composing Mail

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


File: mailutils.info,  Node: Getting Help on Compose Escapes,  Next: Editing the Message,  Prev: Quitting Compose Mode,  Up: Composing Mail

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


File: mailutils.info,  Node: Editing the Message,  Next: Modifying the Headers,  Prev: Getting Help on Compose Escapes,  Up: Composing Mail

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


File: mailutils.info,  Node: Modifying the Headers,  Next: Enclosing Another Message,  Prev: Editing the Message,  Up: Composing Mail

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


File: mailutils.info,  Node: Enclosing Another Message,  Next: Adding a File to the Message,  Prev: Modifying the Headers,  Up: Composing Mail

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


File: mailutils.info,  Node: Adding a File to the Message,  Next: Attaching a File to the Message,  Prev: Enclosing Another Message,  Up: Composing Mail

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


File: mailutils.info,  Node: Attaching a File to the Message,  Next: Printing And Saving the Message,  Prev: Adding a File to the Message,  Up: Composing Mail

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

   The first line of the output shows the content type of the message.
Each subsequent line contains the ordinal number of the attachment, the
name of the file, content-type and transfer encoding used.

   The '~/' escape toggles the content type bewteen 'multipart/mixed',
and 'multipart/alternative'.  The new value of the content type is
displayed on the screen.

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

     ~^ 1


File: mailutils.info,  Node: Printing And Saving the Message,  Next: Signing the Message,  Prev: Attaching a File to the Message,  Up: Composing Mail

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


File: mailutils.info,  Node: Signing the Message,  Next: Printing Another Message,  Prev: Printing And Saving the Message,  Up: Composing Mail

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


File: mailutils.info,  Node: Printing Another Message,  Next: Inserting Value of a Mail Variable,  Prev: Signing the Message,  Up: Composing Mail

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


File: mailutils.info,  Node: Inserting Value of a Mail Variable,  Next: Executing Other Mail Commands,  Prev: Printing Another Message,  Up: Composing Mail

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


File: mailutils.info,  Node: Executing Other Mail Commands,  Next: Executing Shell Commands,  Prev: Inserting Value of a Mail Variable,  Up: Composing Mail

3.5.4.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'.


File: mailutils.info,  Node: Executing Shell Commands,  Prev: Executing Other Mail Commands,  Up: Composing Mail

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


File: mailutils.info,  Node: MIME,  Next: Scripting,  Prev: Composing Mail,  Up: mail

3.5.5 Composing Multipart Messages
----------------------------------

Multipart messages (or MIME, for short) can be used to send text in
character sets other than ASCII, attach non-text files, send multiple
parts in alternative formats, etc.

   Technically speaking, the boolean variable 'mime' controls this
feature.  If it is set (*note Setting and Unsetting the Variables::),
'MIME' will create MIME messages by default.  The variable can be set in
the global or user configuration file (*note Mail Configuration
Files::), using the following command:

     set mime

   It can also be set from the command line, using the '--mime' option.

   GNU 'mail' automatically turns on the MIME mode, when it is requested
to send a non-plaintext message, or a message in character set other
than ASCII, when the encoding is specified, or when attachments are
given.

   To send a message in another character set, specify it with the
'--content-type' option:

     mail --content-type 'text/plain; charset=utf-8'

   The '--encoding' specifies the encoding to use:

     mail --content-type 'text/plain; charset=utf-8' --encoding=base64

   Its argument is any encoding supported by GNU mailutils.  The two
most often used encodings are 'base64' and 'quoted-printable'.

   To specify the charset from 'mail' interactive section, enable the
"edit headers" mode ('set editheaders') and add the needed
'Content-Type' header manually.

   GNU 'mail' also gives you a possibility to attach files to the
message being sent.

   The simplest way to attach a file from command line is by using the
'--attach' ('-A') option.  Its argument specifies the file to attach.
For example, the following will attach the content of the file
'archive.tar':

     $ mail --attach=archive.tar

   By default, the content type will be set to
'application/octet-stream', and the attachment will be encoded using the
'base64' encoding.  To change the content type, use the '--content-type'
option.  For example, to send an HTML attachment:

     $ mail --content-type=text/html --attach=in.html

   The '--content-type' option affects all '--attach' options that
follow it, and the message body (if any).  To change the content type,
simply add another '--content-type' option.  For example, to send both
the HTML file and the archive:

     $ mail --content-type=text/html --attach=in.html \
            --content-type=application/x-tar --attach=archive.tar

   To change the content type of the message body when sending a message
with attachments, use the trailing '--content-type' option, i.e.  the
option not followed by another '--attach' option:

     $ mail --content-type=text/html --attach=in.html \
            --content-type=application/x-tar --attach=archive.tar \
            --content-type=text/plain

This example adds two attachments with different content types and
switched back to the 'text/plain' content type for the message body.

   The encoding to use is set up by the '--encoding' option.  As well as
'--content-type', this option affects all attachments supplied after it
in the command line as well as the message body read from the standard
input, until changed by the eventual next instance of the same option.
Extending the above example:

     $ mail --content-type=text/html --encoding=quoted-printable \
            --attach=in.html \
            --content-type=application/x-tar --encoding=base64 \
            --attach=archive.tar

   A trailing '--encoding' option sets the encoding of the message body.

   Each attachment can also be assigned a "description" and a "file
name".  Normally, these are the same as the file name supplied with the
'--attach' option.  However, you can change either or both of them using
the '--content-name' and '--content-filename', correspondingly.  Both of
these options affect only the next '--attach' (or '--attach-fd', see
below) option.

   By default, the message will be assigned the content type
'multipart/mixed'.  To change it to 'multipart/alternative', use the
'--alternative' command line option.  Using this option also sets the
'Content-Disposition' header of each attached message to 'inline'.

   All the examples above will enter the usual interactive shell,
allowing you to compose the body of the message.  If that's not needed,
the non-interactive use can be forced by redirecting '/dev/null' to the
standard input, e.g.:

     $ mail --attach=archive.tar < /dev/null

   This will normally produce a message saying:

     mail: Null message body; hope that's ok

   To suppress this message, unset the 'nullbodymsg' variable, as shown
in the example below:

     $ mail -E 'set nonullbodymsg' --attach=archive.tar < /dev/null

   The option '--attach=-' forces 'mail' to read the file to be attached
from the standard input stream.  This option disables the interactive
mode and sets 'nonullbodymsg' implicitly, so that the above example can
be rewritten as:

     $ mail --attach=- < archive.tar

   Special option is provided to facilitate the use of 'mail' in
scripts.  The '--attach-fd=N' instructs the program to read the data to
be attached from the file descriptor N.  The above example is equivalent
to:

     $ mail --attach-fd=0 < archive.tar

   Attachments created with this option have neither filename nor
description set, so normally the use of '--content-name' and/or
'--content-filename' is advised.

   The option '--skip-empty-attachments' instructs 'mail' to skip
creating attachments that would have zero-size body.  This option
affects all attachments created by '--attach' and '--attach-fd' options
appearing after it in the command line.  It also affects the handling of
the original message body.  To cancel its effect, use the
'--no-skip-empty-attachments' option.

   Here are some examples illustrating how it works.

   First, consider the following command line

     $ mail --attach=archive.tar </dev/null

   Assume that 'archive.tar' is not empty.

   This will create a MIME message of two parts: the first part having
'text/html' type and empty body, and the second part of type
'application/octet-stream', with the content copied from the file
'archive.tar'.

   Now, if you do:

     $ mail --attach=archive.tar --skip-empty-attachments </dev/null

then the created MIME message will contain only one part: that
containing 'archive.tar'.

   If the file 'archive.tar' has zero length, the resulting archive will
still contain the 'application/octet-stream' part of zero length.
However, if you place the '--skip-empty-attachments' option before
'--attach', then the produced message will be empty.

   The following Perl program serves as an example of using 'mail' from
a script to construct a MIME message on the fly.  It scans all mounted
file systems for executable files that have setuid or setgid bits set
and reports the names of those files in separate attachments.  Each
attachment is named after the mountpoint it describes.

   The script begins with the usual prologue stating the modules that
will be used:

     #!/usr/bin/perl

     use strict;
     use autodie;

   Then global variables are declared.  The '@rcpt' array contains the
email addresses of the recipients:

     my @rcpt= 'root@example.com';

   The '@cmd' variable holds the 'mail' command line.  It will be
augmented for each file system.  The initial value is set as follows:

     my @cmd = ('mail',
                '-E set nonullbodymsg',
                '--content-type=text/plain');

   The 'find' utility will be used to locate the files.  The script will
start as many instances as there are mountpoints.  Those instances will
be run in parallel and their standard output streams will be connected
to file descriptors passed to 'mail' invocation in '--attach-fd'
options.

   The descriptors will be held in '@fds' array.  This will prevent them
from being wiped out by the garbage collector.  Furthermore, care should
be taken to ensure that the 'O_CLOEXEC' flag be not set for these
descriptors.  This sample script takes a simplistic approach: it
instructs Perl not to close first 255 descriptors when executing another
programs:

     my @fds;
     $^F = 255;

   The following code obtains the list of mount points:

     open(my $in, '-|', 'mount -t nonfs,noproc,nosysfs,notmpfs');
     while (<$in>) {
         chomp;
         if (/^\S+ on (?<mpoint>.+) type (?<fstype>.+) /) {

   For each mountpoint, the 'find' command line is constructed and
launched.  The file descriptor is pushed to the '@fds' array to prevent
it from being collected by the garbage collector:

     	open(my $fd, '-|',
     	     "find $+{mpoint} -xdev -type f"
                  . " \\( -perm -u+x -o -perm -g+x -o -perm -o+x \\)"
                  . " \\( -perm -u+s -o -perm -g+s \\) -print");
     	push @fds, $fd;

   Now, the 'mail' command is instructed to create next attachment from
that file descriptor:

             my $mpname = $+{mpoint};
             $mpname =~ tr{/}{%};
             push @cmd,
                  "--content-name=Set[ug]id files on $+{mpoint} (type $+{fstype})",
                  "--content-filename=$mpname.list",
                  '--attach-fd=' . fileno($fd);
         }
     }
     close $in;

   Finally, the emails of the recipients are added to the command line,
the standard input is closed to make sure 'mail' won't enter the
interactive mode and the constructed command is executed:

     push @cmd, @rcpt;
     close STDIN;
     system(@cmd);


File: mailutils.info,  Node: Scripting,  Next: Mail Variables,  Prev: MIME,  Up: mail

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

   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@example.com gray@example.org
     set


File: mailutils.info,  Node: Mail Variables,  Next: Mail Configuration Files,  Prev: Scripting,  Up: mail

3.5.7 How to Alter the Behavior of 'mail'
-----------------------------------------

Following variables control the behavior of GNU 'mail':

 -- mail: boolean append

     Default: True
     Comment: Read-Only

     Messages saved in 'mbox' are appended to the end, rather than
     prepended.  This is the default and cannot be changed.  This
     variable exists only for compatibility with other 'mailx'
     implementations.

 -- mail: boolean appenddeadletter

     Default: False

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

 -- mail: boolean askbcc

     Default: False

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

 -- mail: boolean askcc

     Default: True

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

 -- mail: boolean asksub

     Default: True in interactive mode, False otherwise.

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

 -- mail: boolean autoinc

     Default: True

     Automatically incorporate newly arrived messages.

 -- mail: boolean autoprint

     Default: False

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

 -- mail: boolean bang

     Default: False

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

     *Note Executing Shell Commands::, for details on the '!' escape.

 -- mail: boolean datefield

     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.

     *Note fromfield::.

 -- mail: string charset

     Default: 'auto'

     The value of this variable is the character set used for input and
     output operations.  If the value is 'auto', 'mail' will try to
     deduce the name of the character set from the value of 'LC_ALL'
     environment variable.  If the variable contains the character set
     part (e.g.  'nb_NO.utf-8'), it will be used.  Otherwise, 'mail'
     will look up in its built-in database the value of the character
     for this language/territory combination.  If 'LC_ALL' is not set,
     the 'LANG' environment variable is inspected.

     The value of 'charset' controls both input and output operations.
     On input, it is used to set the value of the 'charset' parameter in
     the 'Content-Type' MIME header, if its value begins with 'text/'
     and the 'charset' parameter is not present.

     On output, it is used to display values of the header fields
     encodied using RFC 2047.  If the variable is unset, no decoding is
     performed and the fields are printed as they are.  Otherwise, they
     are recoded to that character set.

 -- mail: string cmd

     Default: Unset

     Contains default shell command for 'pipe'.

 -- mail: numeric columns

     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.

 -- mail: numeric crt
 -- mail: boolean crt

     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.

 -- mail: boolean debug
 -- mail: string debug

     Default: Unset

     Sets mailutils debug level.  If set to string, the value must be a
     valid Mailutils debugging specification.  *Note 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.

 -- mail: string decode-fallback

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

 -- mail: boolean dot

     Default: False

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

 -- mail: boolean editheaders

     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.

 -- mail: boolean emptystart

     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.

 -- mail: string escape

     Default: '~'

     Current value of the command escape character.

 -- mail: boolean flipr

     Default: Unset

     If set, the variable 'flipr' swaps the meanings of 'reply' and
     'Reply' commands (*note Replying::).

 -- mail: string folder

     Default: Unset

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

 -- mail: boolean fromfield

     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.

     *Note datefield::.

 -- mail: boolean fullnames

     Default: True

     Preserve personal parts (comments) of recipient addresses when
     replying to a message.

     When unset, only emails will be used.

     *Note Replying::.

 -- mail: boolean header

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

     Whether to run 'headers' command automatically after entering
     interactive mode.

 -- mail: string headline

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

     Format string to use for the header summary.  The '%' character
     introduces a "format specifier".  The format specifier consists of
     optional alignment specifier ('+' or '-' sign), optional output
     width and the specifier letter.  Format specifiers are replaced on
     output with the corresponding piece of information from the message
     being described.

     The '-' character immediately following '%' indicates that this
     field should be left aligned.  The '+' character indicates right
     alignment.  Default alignment depends on the type of the specifier:
     the specifiers that produce numeric values ('%l', '%m', and '%o')
     are aligned to the right, whereas the ones producing string or
     date/time values are aligned to the left.

     A number following '%' or the alignment flag, indicates the field
     width.

     Consider the '%m' specifier as an example:

     %m
          Print current message number.  Take as much screen columns as
          necessary for output.

     %4m
     %+4m
          Print current message number.  Use exactly 4 screen columns,
          truncating the output if it does not fit that width.  Align
          the output to the right.

     %-4m
          Same as above, but align to the left.

     Valid format specifiers are:

     %a
          Message attribute.  One of the following letters, or a single
          horizontal space, if none of them applies:

          'M'            the message was copied to the mailbox
                         ('mbox' command)
          'P'            the message was preserved ('hold'
                         command)
          '*'            the message was saved ('save' or 'Save')
          'T'            the message was tagged ('tag')
          'R'            the message was read
          'N'            the message is new (was not seen)
          'U'            the message was seen, but wasn't read

     %d
          The date when the message was received.  It is determined from
          the message header defined by the 'datefield' variable (*note
          datefield::).  If that variable is not set, or the requested
          header is not present in the message, the date from the
          envelope is used.

          The output is formatted according to the following format
          specification (*note Date/time Format String::):

               %a %b %e %H:%M

          I.e.: abbreviated weekday name, abbreviated month name, day of
          the month as a decimal number, followed by hour and minutes.
          All names are displayed according to the current locale.

     %D{FMT}
          Same as '%d', but the date is formatted according to the
          date/time format FMT.  It is essentially a C 'strftime' format
          string, described in detail in *note Date/time Format
          String::.

          For example:

               set headline="%4m %20D{%Y-%m-%dT%H:%M:%S}"

          Note, that the opening '{' must follow the format letter
          without any intervening whitespace.  If FMT contains '{', '}',
          or '\', these characters must be escaped with backslash (e.g.
          '\{').

     %DF
          A simplified form of the '%D' specifier.  It is equivalent to

               %D{%F}

          where F is a single 'strftime' specifier letter.  It can be
          preceded by 'E' or 'O', if the Single UNIX Specification
          allows such usage (*note conversion specs::), e.g.  '%DOU'.

          Notice, that '%D' not followed by a valid time format in
          either of the above forms is treated as unknown specifier.

     %f
          The email address of the message sender.

     %l
          The number of lines of the message.

     %m
          Message number.

     %o
          The number of octets (bytes) in the message.

     %s
          Message subject (if any).

     %S
          Message subject (if any) in double quotes.

     %>
          A '>' for the current message, otherwise a space.

     %<
          A '<' for the current message, otherwise a space.

     %%
          A '%' character.

 -- mail: boolean hold

     Default: False

     Determines the location where to store the messages in state 'read'
     and (if the 'keepsave' is also set) 'saved'.  When set, these
     messages will be retained in the system mailbox.

     When not set (the default), such messages will be stored in the
     user's personal mailbox.

     *Note read messages::, and *Note saved messages::, for a detailed
     information on how such messages are processed when the mailbox is
     being closed.

     *Note keepsave::, for the discussion of the 'keepsave' variable.

 -- mail: boolean ignore

     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.

 -- mail: boolean ignoreeof

     Default: False

     Controls whether typing EOF character terminates the letter being
     composed.

 -- mail: string indentprefix

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

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

 -- mail: boolean inplacealiases

     Default: False

     If set, 'mail' will expand aliases in the address header field
     before entering send mode (*note Composing Mail::).  By default,
     the address header fields are left intact while composing, the
     alias expansion takes place immediately before sending message.

 -- mail: boolean keep

     Comment: Read-Only
     Default: True

     Truncate the user's system mailbox when it is empty, instead of
     removing it.  This is the default and cannot be changed.  This
     variable exists only for compatibility with other 'mailx'
     implementations.

 -- mail: boolean keepsave

     Default: False

     Controls whether saved messages should be retained.  The location
     where they will be retained is controlled by the 'hold' variable
     (*note the hold variable::).

     This variable is in effect only when operating upon the user's
     system mailbox.

     *Note saved messages::, for a detailed information on how the saved
     messages are processed when the mailbox is being closed.

 -- mail: boolean mailx

     Default: False

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

        * When composing a message 'mail' will ask for 'Cc' and 'Bcc'
          addresses after composing the body.  The default behavior is
          to ask for these values before composing the body.

        * In send mode, if the composition was interrupted, 'mail' will
          exit with zero status.  By default it exits with zero status
          only if the message was sent successfully.

        * The 'outfolder' variable is treated as boolean.  *note
          outfolder::.

        * The value of 'outfilename' is ignored (assumed to be 'local').
          *note outfilename::.

        * The values of 'folder' and 'record' variables are assumed
          relative to the home directory, unless they begin with '/',
          '~', or '+'.

        * If the value of the 'sendmail' variable does not begin with a
          scheme specification, 'sendmail:/' is assumed.  *Note sendmail
          mail variable::.

 -- mail: boolean metamail
 -- mail: string metamail

     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"

 -- mail: string mime

     Default: False

     If set, this variable instructs 'mail' to compose MIME messages.

     It can be set from the command line using '--mime' option.

 -- mail: string mimenoask

     Default: Unset

     By default 'mail' asks for confirmation before running interpreter
     to view a part of the multi-part message.  If this variable is set,
     its value is treated as a comma-separated list of MIME types for
     which no confirmation is needed.  Elements of this list may include
     shell-style globbing patterns, e.g.  setting

          set mimenoask=text/*,image/jpeg

     will disable prompting before displaying any textual files, no
     matter what their subtype is, and before displaying files with type
     'image/jpeg'.

 -- mail: boolean metoo

     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.

 -- mail: string mode

     Comment: 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 (*note Invoking Mail::).

     exist
          The program is started with the '--exist' ('-e') command line
          option (*note Invoking Mail::).

     print
          The program is started with the '--print' ('-p') command line
          option (*note 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.

 -- mail: boolean nullbody

     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'

 -- mail: string nullbodymsg

     Default: 'Null message body; hope that's ok'

     Text of the warning displayed by 'mail' before sending an empty
     message.  When available, the translation of this text, in
     accordance with the current locale, is displayed.

     Unsetting this variable disables the warning.

 -- mail: boolean onehop

     Default: Unset

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

 -- mail: string outfilename

     Comment: Three-state: 'local', 'email', 'domain'.
     Default: 'local'

     Defines the algorithm to convert the recipient email to the name of
     the file used to record outgoing messages to that recipient.  This
     affects the following commands: 'Copy', 'Save', 'Mail', 'followup',
     and 'Followup'.  The following values are allowed:

     'local'
          Local part of the email address is taken as the file name.
          This is the default.

     'email'
          Entire email is takes as the file name.

     'domain'
          Domain part of the email is used as the file name.

 -- mail: boolean outfolder
 -- mail: string outfolder

     Default: Unset

     When set as boolean, causes the files used to record outgoing
     messages to be located in the directory specified by the 'folder'
     variable (unless the pathname is absolute).

     If set to a string value, names the directory where to store these
     files.

     This variable affects the following commands: 'Copy', 'Save',
     'Mail', 'followup', and 'Followup'.

     In mailx compatibility mode, only boolean value is allowed.  *note
     mailx mail variable::.

 -- mail: boolean page

     Default: Unset

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

 -- mail: string PID

     Comment: Read-Only
     Default: PID of the process.

     PID of the current 'mail' process.

 -- mail: string prompt

     Default: "?  "

     Contains the command prompt sequence.

 -- mail: boolean quiet

     Default: Unset

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

 -- mail: boolean quit

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

     When set, causes keyboard interrupts to terminate the program.

 -- mail: boolean rc

     Default: True, unless started with '--norc' ('-N') option.

     When this variable is set, 'mail' will read the system-wide
     configuration file upon startup.  *Note Mail Configuration Files::.

 -- mail: boolean readonly

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

 -- mail: string record

     Default: Unset

     When set, outgoing messages produced by the following commmands
     will be saved to the named file: 'mail', 'reply', 'Reply'.

     See also *note outfolder:: and *note outfilename::.

 -- mail: boolean recursivealiases

     Default: True

     When set, 'mail' will expand aliases recursively.

 -- mail: boolean regex

     Default: True.

     If set, enables the use of regular expressions in '/.../' message
     specifications.

 -- mail: string replyprefix

     Default: 'Re: '

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

 -- mail: string replyregex

     Default: '^re: *'

     Sets the regular expression used to recognize subjects of reply
     messages.  If the 'Subject' header of the message matches this
     expression, the value of 'replyprefix' will not be prepended to it
     before replying.  The value should be a POSIX extended regular
     expression.  The comparison is case-insensitive.

     For example, to recognize usual English, Polish, Norwegian and
     German reply subject styles, use:

          set replyregex="^(re|odp|aw|ang)(\\[[0-9]+\\])?:[[:blank:]]"

     (Notice the quoting of backslash characters).

 -- mail: string return-address

     Default: unset

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

 -- mail: boolean save

     Default: True.

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

 -- mail: numeric screen

     Default: Detected at startup by querying the terminal device.  If
     this fails, the value of environment variable 'LINES' is used.

     This variable contains the number of lines on terminal screen.  See
     also *note crt::.

 -- mail: string sendmail

     Default: 'sendmail:/usr/lib/sendmail'

     Contains URL of the mail transport agent.  If the value begins with
     a scheme specifier, it must be one of the mailer URL schemes
     supported by mailutils (*note mailer URL::).  Otherwise, if not in
     mailx compatibility mode, the value starting with directory
     separator ('/') is treated as the external command that will be
     started as is and the composed message will be piped to its
     standard input.

     In mailx compatibility mode (*note mailx mail variable::), the
     'sendmail:' prefix is assumed.

 -- mail: boolean sendwait

     Default: Unset

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

 -- mail: string Sign

     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.

 -- mail: string sign

     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.

 -- mail: boolean showenvelope

     Default: Unset

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

 -- mail: boolean showto

     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.

 -- mail: string subject

     Default: Unset

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

 -- mail: numeric toplines

     Default: 5

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

 -- mail: boolean variable-pretty-print
 -- mail: boolean varpp

     Default: False

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

 -- mail: boolean variable-strict
 -- mail: boolean varstrict

     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.

     *Note Setting and Unsetting the Variables::.

 -- mail: boolean verbose

     Default: False

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

 -- mail: boolean useragent

     Default: True

     Controls whether the 'User-Agent' header should be added to
     outgoing messages.  The default value of this header is

          User-Agent: mail (GNU Mailutils 3.17)

 -- mail: boolean xmailer
     This header is retained for compatibility with previous releases of
     GNU Mailutils.  Since version 3.13 it is an alias for 'useragent'.


File: mailutils.info,  Node: Mail Configuration Files,  Prev: Mail Variables,  Up: mail

3.5.8 Personal and System-wide Configuration Files
--------------------------------------------------

After processing the usual Mailutils configuration files (*note
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'.


File: mailutils.info,  Node: messages,  Next: movemail,  Prev: mail,  Up: Programs

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

Statement              Reference
-------------------------------------------------------------------
debug                  *Note debug statement::.
tls                    *Note tls statement::.
mailbox                *Note mailbox statement::.
locking                *Note locking statement::.

   In addition to the common mailutils options (*note 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.


File: mailutils.info,  Node: movemail,  Next: readmsg,  Prev: messages,  Up: Programs

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.
*Note (emacs)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
(http://mailutils.org/wiki/Fetching_Mail_with_Movemail), for a detailed
discussion with usage recipes.

* Menu:

* Movemail Configuration::
* Ownership::            Setting Destination Mailbox Ownership
* Summary::              Short Movemail Invocation Summary


File: mailutils.info,  Node: Movemail Configuration,  Next: Ownership,  Up: movemail

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 (*note 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:

Statement              Reference
-------------------------------------------------------------------
debug                  *Note debug statement::.
tls                    *Note tls statement::.
mailbox                *Note mailbox statement::.
locking                *Note locking statement::.
pam                    *Note pam statement::.
sql                    *Note sql statement::.
virtdomain             *Note virtdomain statement::.
radius                 *Note radius statement::.
ldap                   *Note ldap statement::.
auth                   *Note auth statement::.


File: mailutils.info,  Node: Ownership,  Next: Summary,  Prev: Movemail Configuration,  Up: movemail

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


File: mailutils.info,  Node: Summary,  Prev: Ownership,  Up: movemail

3.7.3 Movemail Usage Summary
----------------------------

     movemail [OPTION...] INBOX DESTFILE [PASSWORD]

   The first argument, INBOX, is the url (*note 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.(1).

   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.  *Note onerror statement: movemail-onerror,
     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.  *Note
     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).
     *Note 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 (*note Common Options::).

   ---------- Footnotes ----------

   (1) Rmail does not use this feature


File: mailutils.info,  Node: readmsg,  Next: decodemail,  Prev: movemail,  Up: Programs

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 by default.  This can changed using
     the '-i' ('--ignorecase') option.  Two more options are provided to
     control the matching algorithm: the '-g' ('--glob') option
     instructs 'readmsg' to treat arguments as shell globbing patterns
     and the '-r' ('--regex') option instructs it to treat them as POSIX
     extended regular expressions.  Needless to say, when using any of
     the two latter options, you should pay attention to escape the
     matching pattern to prevent it from being interpreted by the shell.
     E.g.:

          readmsg --regex 'staff.*meeting'

   Unless requested otherwise, only the first message that matches the
pattern is printed.

   At least one command line argument or one informational option must
be present in 'readmsg' invocation.  Informational options are: '--help'
('-?'), '--usage', and '--version' ('-V').

* Menu:

* Opt-readmsg::   Invocation of 'readmsg'.
* Conf-readmsg::  Configuration of 'readmsg'.


File: mailutils.info,  Node: Opt-readmsg,  Next: Conf-readmsg,  Up: readmsg

3.8.1 Invocation of 'readmsg'.
------------------------------

'-a'
'--show-all'
     If a pattern is used for selection, show all messages that match
     pattern by default only the first one is presented.

'-d'
'--debug'
     Display mailbox debugging information.

'-e'
'--exact'
     Look for messages containing exactly the words given as arguments.
     This is the default.  Other options changing this behavior are:
     '--glob', '--regex', and '--ignorecase'.

'-f MAILBOX'
'--folder=MAILBOX'
     Specified the default mailbox.

'-g'
'--glob'
     Treat non-option arguments as shell globbing patterns.  For
     example, to select the first message with words 'morning' and
     'coffee' with anything bewteen them:

          readmsg --glob 'morning*coffee'

     (notice quoting, which prevents the shell from interpreting the '*'
     prematurely).

'-h'
'--header'
     Show the entire header and ignore the weedlist.

'-i'
'--ignorecase'
     Ignore the case of letters when looking for matching messages.
     E.g.:

          readmsg --glob --ignorecase 'morning*coffee'

'-n'
'--no-header'
     Do not print the message header.

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

'-r'
'--regex'
     Treat non-option arguments as POSIX extended regular expressions.

'-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 *note Common Options::.


File: mailutils.info,  Node: Conf-readmsg,  Prev: Opt-readmsg,  Up: readmsg

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 (*note
     -weedlist: Opt-readmsg.).

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

Statement              Reference
-------------------------------------------------------------------
debug                  *Note Debug Statement::.
tls                    *Note TLS Statement::.
mailbox                *Note Mailbox Statement::.
locking                *Note Locking Statement::.


File: mailutils.info,  Node: decodemail,  Next: sieve,  Prev: readmsg,  Up: Programs

3.9 'decodemail' - Decode multipart messages
============================================

The 'decodemail' utility is a filter program that reads messages from
the input mailbox, decodes "textual" parts of each multipart message
from a base64- or quoted-printable encoding to an 8-bit or 7-bit
transfer encoding, and stores the processed messages in the output
mailbox.  All messages from the input mailbox are stored in the output,
regardless of whether a change was made.

   The message parts deemed to be textual are those whose 'Content-Type'
header matches a predefined, or user-defined, mime type pattern.  In
addition, encoded pieces of the 'From:', 'To:', 'Subject:', etc.,
headers are decoded.

   For example, 'decodemail' makes this transformation:

     Subject: =?utf-8?Q?The=20Baroque=20Enquirer=20|=20July=202020?=
     => Subject: The Baroque Enquirer | July 2020

   The built-in list of textual content type patterns is:

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

   These strings are matched as shell globbing patterns (*note
(glob(7))glob::).

   More patterns can be added to this list using the 'mime.text-type'
configuration statement.  *Note mime statement::, for a detailed
discussion, and the configuration section below for a simple example.

   When processing old mesages you may encounter 'Content-Type' headers
whose value contains only type, but no subtype.  To match such headers,
use the pattern without '/whatever' part.  E.g.  'text/*' matches
'text/plain' and 'text/html', but does not match 'text'.  On the other
hand, 't*xt' does not match 'text/plain', but does match 'text'.

   Optionally, the decoded parts can be converted to another character
set.  By default, the character set is not changed.

* Menu:

* Opt-decodemail::   Invocation of 'decodemail'.
* Conf-decodemail::  Configuration of 'decodemail'.
* Using-decodemail:: Purpose and caveats of 'decodemail'.


File: mailutils.info,  Node: Opt-decodemail,  Next: Conf-decodemail,  Up: decodemail

3.9.1 Invocation of 'decodemail'.
---------------------------------

Usually, the utility is invoked as:

     decodemail INBOX OUTBOX

where INBOX and OUTBOX are file names or URLs of the input and output
mailboxes, correspondingly.  The input mailbox is opened read-only and
will not be modified in any way.  In particular, the status of the
processed messages will not change.  If the output mailbox does not
exist, it will be created.  If it exists, the messages will be appended
to it, preserving any original messages that are already in it.  This
behavior can be changed using the '-t' ('--truncate') option, described
below.

   The two mailboxes can be of different types.  For example you can
read input from an imap server and store it in local 'maildir' box using
the following command:

     decodemail imap://user@example.com maildir:///var/mail/user

   Both arguments can be omitted.  If OUTBOX is not supplied, the
resulting mailbox will be printed on the standard output in Unix 'mbox'
format.  If INBOX is not supplied, the utility will open the system
inbox for the current user and use it for input.

   A consequence of these rules is that there is no simple way to read
the input mailbox from standard input (the input must be seekable).  If
you need to do this, the normal procedure would be to save what would be
standard input in a temporary file and then give that file as
'decodemail''s input.

   The following command line options modify the 'decodemail' behavior:

'-c, --charset=CHARSET'
     Convert all textual parts from their original character set to the
     specified CHARSET.

'-R, --recode'
     Convert all textual parts from their original character set to the
     current character set, as specified by the 'LC_ALL' or 'LANG'
     environment variable.

'--no-recode'
     Do not convert character sets.  This is the default.

'-t, --truncate'
     If the output mailbox exists, truncate it before appending new
     messages.

'--no-truncate'
     Keep the existing messages in the output mailbox intact.  This is
     the default.

   Additionally, the *note Common Options:: are also understood.


File: mailutils.info,  Node: Conf-decodemail,  Next: Using-decodemail,  Prev: Opt-decodemail,  Up: decodemail

3.9.2 Configuration of 'decodemail'.
------------------------------------

The following common configuration statements affect the behavior of
'decodemail':

Statement              Reference
-------------------------------------------------------------------
mime                   *Note mime statement::.
debug                  *Note Debug Statement::.
mailbox                *Note Mailbox Statement::.
locking                *Note Locking Statement::.

   Notably, the 'mime' statement can be used to extend the list of types
which are decoded.  For example, in the file '~/.decodemail' (other
locations are possible, *note configuration::), you could have:

     # base64/qp decode these mime types also:
     mime {
       text-type "application/x-bibtex";
       text-type "application/x-tex";
     }

   Since the list of textual mime types is open-ended, with new types
being used at any time, we do not attempt to make the built-in list
comprehensive.


File: mailutils.info,  Node: Using-decodemail,  Prev: Conf-decodemail,  Up: decodemail

3.9.3 Purpose and caveats of 'decodemail'.
------------------------------------------

The principal use envisioned for this program is to decode messages in
batch, after they are received.

   Unfortunately, some mailers prefer to encode messages in their
entirety in base64 (or quoted-printable), even when the content is
entirely human-readable text.  This makes straightforward use of 'grep'
or other standard commands impossible.  The idea is for 'decodemail' to
rectify that, by making the message text readable again.

   Besides personal mail, mailing list archives are another place where
such decoding can be useful, as they are often searched with standard
tools.

   It is generally not recommended to run 'decodemail' within a mail
reader (which should be able to do the decoding itself), or directly in
a terminal (since quite possibly there will be 8-bit output not in the
current character set).

   Although the output message from 'decodemail' should be entirely
equivalent to the input message, apart from the decoding, it is
generally not identical.  Because 'decodemail' parses the input message
and reconstructs it for output, there are usually small differences:

   * In the envelope 'From ' line, multiple spaces are collapsed to one.

   * A 'Content-Transfer-Encoding:' header may be added where not
     previously present, or its value changed from '8bit' to '7bit', or
     vice versa.  This may happen both for the message as a whole, and
     for a given mime part.  'decodemail' looks at the actual content of
     the text and outputs 'Content-Transfer-Encoding:' accordingly.

   * A trailing space is inserted when a long header line is broken to
     occupy several lines ("header wrapping").

          SomeHeader:
            someextremelylongvaluethatcannotbebroken

   * The non-tracing headers may be reordered, notably those that are
     mime-related.

   * Any material before the first mime part of a mime multipart message
     is lost.  By the standards, nothing should appear there.  Typically
     if it does appear, it is a string such as 'This is a multi-part
     message in MIME format.'.

   * In mime parts, the charset specifications may no longer be quoted
     (if quoting is not necessary).  For example, 'charset="utf-8"'
     becomes 'charset=utf-8'.

   * The mime boundary strings will be changed.

   If a discrepancy is created which actually affects message parsing or
reading, that's most likely a bug, and please report it.  Naturally,
please send an exact input message to reproduce the problem.


File: mailutils.info,  Node: sieve,  Next: guimb,  Prev: decodemail,  Up: Programs

3.10 'sieve'
============

  ==================================================================
                           *Editor's note:*
     The information in this node may be obsolete or otherwise
     inaccurate.  This message will disappear, once this node revised.
  ==================================================================

   Sieve is a language for filtering e-mail messages at time of final
delivery, described in RFC 3028.  GNU Mailutils contains stand-alone
"sieve interpreter", which is described in detail below.

* Menu:

* sieve interpreter::   A Sieve Interpreter


File: mailutils.info,  Node: sieve interpreter,  Up: sieve

3.10.1 A Sieve Interpreter
--------------------------

The sieve interpreter 'sieve' allows you to apply Sieve scripts to
arbitrary number of mailboxes.  GNU 'sieve' implements a superset of the
Sieve language as described in RFC 3028.  *Note Sieve Language::, for a
description of the Sieve language.  *Note GNU Extensions::, for a
discussion of differences between the GNU implementation of Sieve and
its standard.

* Menu:

* Invoking Sieve::
* Sieve Configuration::
* Logging and Debugging::
* Extending Sieve::


File: mailutils.info,  Node: Invoking Sieve,  Next: Sieve Configuration,  Up: sieve interpreter

3.10.1.1 Invoking 'sieve'
.........................

The 'sieve' invocation syntax is:

     sieve [OPTIONS] SCRIPT

   Normally, SCRIPT is the name of the disk file with the Sieve script.
If SCRIPT is a single dash, the script is read from the standard input.
If the '-E' ('--expression') option is given, SCRIPT is taken to be the
sieve script text.

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

'-c'
'--compile-only'
     Compile script and exit.

'--clear-library-path'
'--clearpath'
     Clear Sieve library path.  See also *note clear-library-path: Sieve
     Configuration.

'--clear-include-path'
     Clear Sieve include path.  See also *note clear-include-path: Sieve
     Configuration.

'-d[FLAGS]'
'--debug[=FLAGS]'
     Specify debug flags.  The FLAGS argument is a sequence of one or
     more of the following letters:

     'g'                           Enable main parser traces
     'T'                           Enable mailutils traces
     'P'                           Trace network protocols
     't'                           Enable sieve trace
     'i'                           Trace the program instructions

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

'--environment=NAME=VALUE'
     Set sieve environment variable NAME to the VALUE.

'-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 *note email: Sieve Configuration.

'-E,'
'--expression'
     Treat the SCRIPT argument as Sieve program text.

'-I DIR'
'--includedir=DIR'
     Append directory DIR to the list of directories searched for
     include files.  See also *note include-path: Sieve Configuration.

'-f'
'--mbox-url=MBOX'
     Mailbox to sieve (defaults to user's system mailbox).  See also
     *note mbox-url: Sieve Configuration.

'-k'
'--keep-going'
     Keep on going if execution fails on a message.  See also *note
     keep-going: Sieve Configuration.

'-L DIR'
'--libdir=DIR'
     Append directory DIR to the list of directories searched for
     library files.  See also *note library-path: Sieve Configuration.

'--libdir-prefix=DIR'
     Add DIR to the beginning of the list of directories searched for
     library files.

'--line-info=BOOL'
     Print source location along with action logs (default).

'-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 *note ticket:
     Sieve Configuration.

'--variable=NAME=VALUE'
     Set Sieve variable NAME.  This option automatically inserts
     'require "variables"' at the top of the script.

'-v'
'--verbose'
     Log all actions executed.  See also *note verbose: Sieve
     Configuration.

   See also *note Common Options::.


File: mailutils.info,  Node: Sieve Configuration,  Next: Logging and Debugging,  Prev: Invoking Sieve,  Up: sieve interpreter

3.10.1.2 Sieve Configuration
............................

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

Statement              Reference
-------------------------------------------------------------------
debug                  *Note debug statement::.
tls                    *Note tls statement::.
mailbox                *Note mailbox statement::.
locking                *Note locking statement::.
logging                *Note logging statement::.
mailer                 *Note 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.  *Note 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.  *Note 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.


File: mailutils.info,  Node: Logging and Debugging,  Next: Extending Sieve,  Prev: Sieve Configuration,  Up: sieve interpreter

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


File: mailutils.info,  Node: Extending Sieve,  Prev: Logging and Debugging,  Up: sieve interpreter

3.10.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 (*note libdir-prefix:
          Invoking Sieve.), or the 'library-path-prefix' configuration
          statement (*note library-path-prefix: Sieve Configuration.).

       4. Additional search directories specified with the
          'library-path' statement (*note library-path: Sieve
          Configuration.) in Sieve configuration file.

       5. Additional search directories specified with the.  '--libdir'
          command line option (*note libdir: Invoking Sieve.).

       6. Additional search directories specified with the '#searchpath'
          Sieve directive (*note #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


File: mailutils.info,  Node: guimb,  Next: mda,  Prev: sieve,  Up: Programs

3.11 '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

* Menu:

* Specifying Scheme Program to Execute::
* Specifying Mailboxes to Operate Upon::
* Passing Options to Scheme::
* Command Line Option Summary::


File: mailutils.info,  Node: Specifying Scheme Program to Execute,  Next: Specifying Mailboxes to Operate Upon,  Up: guimb

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 (*note 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.


File: mailutils.info,  Node: Specifying Mailboxes to Operate Upon,  Next: Passing Options to Scheme,  Prev: Specifying Scheme Program to Execute,  Up: guimb

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.


File: mailutils.info,  Node: Passing Options to Scheme,  Next: Command Line Option Summary,  Prev: Specifying Mailboxes to Operate Upon,  Up: guimb

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


File: mailutils.info,  Node: Command Line Option Summary,  Prev: Passing Options to Scheme,  Up: guimb

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.


File: mailutils.info,  Node: mda,  Next: lmtpd,  Prev: guimb,  Up: Programs

3.12 mda
========

GNU local mail delivery agent reads a message from its standard input
and delivers it to one or more local recipients listed in the command
line.  When we speak about local recipients, we mean that these are
system users that are known to the system that runs 'mda'.  However, the
mailboxes of these users can be local as well as remote ones.  'mda' is
able to deliver mail to any mailbox format, supported by GNU Mailutils.
These formats, among others, include 'smtp://', 'prog://' and
'sendmail://' which are equivalent to forwarding a message over SMTP to
a remote node.

   'Mda' is also able to process incoming messages using Sieve, Scheme
or Python scripts and, based on results of this processing, to take a
decision on whether to actually deliver and where to deliver them.  Due
to its extensive scripting facilities, 'mda' offers much more
flexibility than other popular MDAs.

* Menu:

* Sendmail-mda::         Using 'mda' with Sendmail.
* Exim-mda::             Using 'mda' with Exim.
* MeTA1-mda::            Using 'mda' with MeTA1.
* Mailbox Quotas::
* MDA Scripting::
* Forwarding::
* Conf-mda::             'mda' Configuration File Summary.
* Mailing lists::        How to implement Mailing Lists with 'mda'.


File: mailutils.info,  Node: Sendmail-mda,  Next: Exim-mda,  Up: mda

3.12.1 Using 'mda' with Sendmail.
---------------------------------

When used with Sendmail, 'mda' must be invoked from the local mailer
definition in the 'sendmail.cf' file.  The flags 'lswS' must be set for
the mailer.  These mean: the mailer is local, quote characters should be
stripped off the address before invoking the mailer, the user must have
a valid account on this machine and the userid should not be reset
before calling the mailer.  Additionally, the 'fn' flags may be
specified to allow 'mda' to generate the usual 'From ' envelope instead
of the one supplied by 'sendmail'.

   If you wish to use 'mda' with non-local authentication, such as SQL
or LDAP, you also need to remove the 'w' flag, since in that case the
user is not required to have a valid account on the machine that runs
'sendmail'.

   Here is an example of mailer definition in 'sendmail.cf'

     Mlocal, P=/usr/local/sbin/mda,
             F=lsDFMAw5:/|@qSPfhn9,
             S=EnvFromL/HdrFromL, R=EnvToL/HdrToL,
             T=DNS/RFC822/X-Unix,
             A=mail $u

   To define local mailer in 'mc' source file, it will suffice to set:

     define(`LOCAL_MAILER_PATH', `/usr/local/sbin/mda')
     define(`LOCAL_MAILER_ARGS', `mail $u')


File: mailutils.info,  Node: Exim-mda,  Next: MeTA1-mda,  Prev: Sendmail-mda,  Up: mda

3.12.2 Using 'mda' with Exim.
-----------------------------

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

     # transport
     mda_pipe:
       driver = pipe
       command = /usr/local/sbin/mda $local_part
       return_path_add
       delivery_date_add
       envelope_to_add

     # director
     mda:
       driver = localuser
       transport = mda_pipe


File: mailutils.info,  Node: MeTA1-mda,  Next: Mailbox Quotas,  Prev: Exim-mda,  Up: mda

3.12.3 Using 'mda' with MeTA1.
------------------------------

MeTA1 (<http://meta1.org>) communicates with the delivery agent using
LMTP.  Instead of using 'mda' you will have to start the LMTP daemon
'lmtpd' and configure MeTA1 to communicate with it.  *Note
MeTA1-lmtpd::, for details.


File: mailutils.info,  Node: Mailbox Quotas,  Next: MDA Scripting,  Prev: MeTA1-mda,  Up: mda

3.12.4 Mailbox Quotas
---------------------

"Mailbox quota" is a limit on the size of the mailbox.  When a mailbox
size reaches this limit, 'mda' stops accepting messages for this
recipient and returns an error condition to the sender.  The error code
is accompanied by the following error message:

     USER: mailbox quota exceeded for this recipient

   Furthermore, if accepting the incoming message would make the mailbox
size exceed the quota, such a message will be rejected as well.  In this
case, the error message is:

     USER: message would exceed maximum mailbox size for this recipient

   In both cases, the default return code will be 'service unavailable'
(corresponding to the SMTP return code '550'), unless the following
statement is present in the 'maidag' configuration file:

     quota {
       exit-tempfail yes;
     }

in which case a temporary error will be returned.

   The mailbox quota can be retrieved from the following sources:

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

* Menu:

* DBM Quotas::          Keeping Quotas in DBM File.
* SQL Quotas::          Keeping Quotas in SQL Database.


File: mailutils.info,  Node: DBM Quotas,  Next: SQL Quotas,  Up: Mailbox Quotas

3.12.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 'mda --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 quota database in text form:

     # Default quota value:
     DEFAULT         5mb

     # Following users have unlimited mailbox size
     root            NONE
     smith           NONE

     # Rest of users
     plog            26214400
     karin           10mB

   To use the DBM quota database, specify its absolute name using the
'database' configuration statement in the 'quota' section, e.g.:

     quota {
       database /etc/mail/quota.db;
     }


File: mailutils.info,  Node: SQL Quotas,  Prev: DBM Quotas,  Up: Mailbox Quotas

3.12.4.2 Keeping Quotas in SQL Database
.......................................

User quotas can be kept in an SQL table as well.  Currently (as of
mailutils version 3.17) it is assumed that this table can be accessed
using the credentials set in 'sql' configuration statement (*note SQL
Statement::).

   For example, suppose you have the following quota table:

     create table mailbox_quota (
       user_name varchar(32) binary not null,
       quota int,
       unique (user_name)
     );


   To retrieve user quota the following query can be used:

     SELECT quota FROM mailbox_quota WHERE user_name='${user}'

   To define this query use the 'sql-query' statement:

     quota {
       sql-query "SELECT quota "
                 "FROM mailbox_quota "
                 "WHERE user_name='${user}'";
     }

   There are no special provisions for specifying group quotas, similar
to 'DEFAULT' in DBM databases.  This is because group quotas can easily
be implemented using SQL language.  'Mda' always uses the first tuple
from the set returned by mailbox quota query.  So, you can add a special
entry to the 'mailbox_quota' table that would keep the group quota.  In
the discussion below we assume that the 'user_name' column for this
entry is lexicographically less than any other user name in the table.
Let's suppose the group quota name is '00DEFAULT'.  Then the following
query:

     SELECT quota
     FROM mailbox_quota
     WHERE user_name IN ('${user}','00DEFAULT')
     ORDER BY user_name DESC

will return two tuples if the user is found in 'mailbox_quota'.  Due to
'ORDER' statement, the first tuple will contain quota for the user,
which will be used by 'mda'.  On the other hand, if the requested user
name is not present in the table, the above query will return a single
tuple containing the group quota.

   The following configuration statement instructs 'maidag' to use this
query for retrieving the user quota:

     quota {
       sql-query "SELECT quota "
                 "FROM mailbox_quota "
                 "WHERE user_name IN ('${user}','00DEFAULT') "
                 "ORDER BY user_name DESC";
     }


File: mailutils.info,  Node: MDA Scripting,  Next: Forwarding,  Prev: Mailbox Quotas,  Up: mda

3.12.5 Scripting in 'mda'
-------------------------

'Mda' 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.17, such mail filters may be written in the following languages:

   * Sieve *Note Sieve Language::.

   * Scheme
   * Python

   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:

     script {
       language python;
       pattern "~/.maidag-py-filter";
     }

* Menu:

* Sieve MDA Filters::
* Scheme MDA Filters::
* Python MDA Filters::


File: mailutils.info,  Node: Sieve MDA Filters,  Next: Scheme MDA Filters,  Up: MDA Scripting

3.12.5.1 Sieve MDA Filters
..........................

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

     script {
       pattern "~/.maidag.sv";
     }

instructs 'maidag' to use file '.maidag.sv' in the recipient home
directory as a Sieve filter.

   Normal message delivery is attempted if execution of the Sieve code
ended with 'keep' action (either implicit or explicit).

   Other Sieve actions are executed as described in *note 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.


File: mailutils.info,  Node: Scheme MDA Filters,  Next: Python MDA Filters,  Prev: Sieve MDA Filters,  Up: MDA Scripting

3.12.5.2 Scheme MDA Filters
...........................

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

     script {
       pattern "~/.maidag.scm";
     }

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


File: mailutils.info,  Node: Python MDA Filters,  Prev: Scheme MDA Filters,  Up: MDA Scripting

3.12.5.3 Python MDA Filters
...........................

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

     script {
       pattern "~/.maidag.py";
     }

instructs 'mda' to use the file '.maidag.py' in the recipient home
directory as a Python filter.

A simple example of a mail filter written in Python:

     from mailutils import *
     import maidag
     import re

     msg = message.Message (maidag.message)
     hdr = msg.header

     try:
         if 'List-Post' in hdr and 'Received' in hdr \
            and hdr['Received'].find ('fencepost.gnu.org') != -1:

             # check envelope's sender address
             m = re.search (r'([\w\-]+)-bounces\+([\w]+)=.*',
                            msg.envelope.get_sender ())
             if m:
                 lbox = m.group (1)
                 user = m.group (2)
                 # open destination mailbox and append message
                 dst = mailbox.MailboxDefault ('~/Mail/%s' % lbox)
                 dst.open ('ac')
                 dst.append_message (msg)
                 dst.close ()
                 # set deleted flag so maidag will not deliver msg elsewhere
                 msg.attribute.set_deleted ()
     except Exception:
         pass


File: mailutils.info,  Node: Forwarding,  Next: Conf-mda,  Prev: MDA Scripting,  Up: mda

3.12.6 Forwarding
-----------------

A "forward file" is a special file in the user's home directory that
contains the email address of the mailbox where the user wants to
forward his mail.  Normally, forward files are processed by MTA.
However, there are some MTA that lack this feature.  One of them is
MeTA1.

   'Mda' provides a forwarding feature that is useful to compensate the
lack of it.  This feature is controlled by the 'forward' section in the
configuration file:

     forward {
       # Process forward file.
       file NAME;
       # Configure safety checks for the forward file.
       file-checks (LIST);
     }

   The name of the forward file is given by the 'file' statement in the
'forward' section.  A common usage is:

     forward {
       file .forward;
     }

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

   Before actually using the forward file, a number of safety checks are
performed on it.  If the file fails to pass one of these checks, no
forwarding is performed and the message is delivered as usual.  These
checks are configured using the 'forward.file-checks' statement:

     forward {
       file .forward;
       file-checks (LIST);
     }

   Its argument is a list of the following keywords:

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 'file-checks all'.

   Each of these keywords may be prefixed by 'no' to disable this
particular check.  For example:

     forward {
       file-checks (nodir_iwoth, nodir_iwgrp);
       file .forward;
     }


File: mailutils.info,  Node: Conf-mda,  Next: Mailing lists,  Prev: Forwarding,  Up: mda

3.12.7 MDA Configuration File Summary
-------------------------------------

The behavior of 'mda' is affected by the following configuration
statements:

Statement              Reference
-------------------------------------------------------------------
debug                  *Note debug statement::.
mailbox                *Note mailbox statement::.
locking                *Note locking statement::.
pam                    *Note pam statement::.
sql                    *Note sql statement::.
virtdomain             *Note virtdomain statement::.
radius                 *Note radius statement::.
ldap                   *Note ldap statement::.
auth                   *Note auth statement::.
mailer                 *Note mailer statement::.

 -- MDA Config: stderr BOOL
     If BOOL is true, log to standard error instead of syslog.

 -- MDA Config: deliver { ... }
     This section contains general delivery settings:

          deliver {
            domain STRING;
            exit-multiple-delivery-success ARG;
          };

 -- deliver: domain NAME
     Default email domain.

 -- deliver: exit-multiple-delivery-success ARG;
     In case of multiple delivery, exit with code 0 if at least one
     delivery succeeded.

 -- MDA Config: forward { ... }
     Controls the forwarding support:

          forward {
            file NAME;
            file-checks (LIST);
          }

 -- forward: file NAME
     Defines the name of the forward file.  E.g.:

          forward {
            file .forward;
          }

     *Note Forwarding::, for a detailed description.

 -- forward: file-checks (LIST)
     Configures safety checks to be performed on the forward file prior
     to using it.  *Note Forwarding::, for a detailed description.

 -- MDA Config: quota { ... }
     This section configures mail quota support.  *Note Mailbox
     Quotas::, for a detailed description.

          quota {
            database NAME;
            sql-query QUERY;
            exit-tempfail BOOL;
          }

 -- quota: database NAME
     Sets the name of the quota database in DBM format.  *Note DBM
     Quotas::.

 -- quota: sql-query QUERY
     If the quotas are kept in a SQL table, this statement defines the
     SQL query to retrieve the quota for a given user name.  *Note SQL
     Quotas::.

 -- quota: exit-tempfail BOOL
     By default, if a message cannot be delivered because the user has
     exceeded its mail quota, or its delivery would cause it to be
     exceeded, 'MDA' exits with the 'service unavailable' status, which
     causes MTA to return the 550 code.  If 'exit-tempfail' is set to
     true, it will return a temporary error instead.

 -- MDA Config: script { ... }
     Controls scripting.  *Note MDA Scripting::.

          script {
            language LANG;
            pattern GLOB;
          }

 -- script: language LANG
     Defines the language that is used for scripting.  Allowed values
     for LANG are: 'sieve', 'scheme', or 'python'.  *Note scripting
     language::.

 -- script: pattern PAT
     Defines the pattern for the script file name.  The '~' at the
     begiining of the pattern will be replaced with the name of the home
     directory of the recipient user.  The '%u' in pattern will be
     replaced with the recipient user name, and '%h' with the home
     directory for that user.


File: mailutils.info,  Node: Mailing lists,  Prev: Conf-mda,  Up: mda

3.12.8 Mailing list implementation
----------------------------------

This subsection explains how to implement mailing lists in 'mda' using
the 'prog' mailbox scheme.

   Delivery to the 'prog' mailbox results in invoking the specified
command with the given arguments and passing the message to its standard
input.  There are two ways to specify a 'prog' mailbox:

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 can be used to implement mailing lists.

   For example, suppose that the 'mda' configuration contains:

     auth {
       authorization (sql, system);
       authentication (generic, system);
     }

     sql {
       interface mysql;
       db mail;
       getpwnam "SELECT user as name, mailbox, "
                "'x' as passwd, 500 as uid, 2 as gid, "
                "'/nonexistent' as dir, '/sbin/nologin' as shell "
                "FROM userdb "
                "WHERE user='${user}'";
     }

   Then, the following entries in the 'userdb' table implement the
<mailman@yourdomain> mailing list:

     mysql> select * from userdb;
     +---------------------+---------------------------------------+
     | user                | mailbox                               |
     +---------------------+---------------------------------------+
     | mailman             | |/usr/bin/mailman post mailman        |
     | mailman-admin       | |/usr/bin/mailman admin mailman       |
     | mailman-bounces     | |/usr/bin/mailman bounces mailman     |
     | mailman-confirm     | |/usr/bin/mailman confirm mailman     |
     | mailman-join        | |/usr/bin/mailman join mailman        |
     | mailman-leave       | |/usr/bin/mailman leave mailman       |
     | mailman-owner       | |/usr/bin/mailman owner mailman       |
     | mailman-request     | |/usr/bin/mailman request mailman     |
     | mailman-subscribe   | |/usr/bin/mailman subscribe mailman   |
     | mailman-unsubscribe | |/usr/bin/mailman unsubscribe mailman |
     +---------------------+---------------------------------------+


File: mailutils.info,  Node: lmtpd,  Next: putmail,  Prev: mda,  Up: Programs

3.13 lmtpd
==========

The LMTP is a local mail transport protocol defined in RFC 2033.  GNU
Mailutils is shipped with 'lmtpd' - a daemon for delivering messages
using this protocol.

   The daemon shares most of its codebase and configuration with 'mda'
and consequently provides the same features.  *Note mda::, for a
detailed description of these.

   The behavior of 'lmtpd' is affected by the following configuration
statements:

Statement              Reference
-------------------------------------------------------------------
server                 *Note Server Settings::
acl                    *Note acl statement::.
tcp-wrappers           *Note tcp-wrappers statement::.
debug                  *Note debug statement::.
mailbox                *Note mailbox statement::.
locking                *Note locking statement::.
pam                    *Note pam statement::.
sql                    *Note sql statement::.
virtdomain             *Note virtdomain statement::.
radius                 *Note radius statement::.
ldap                   *Note ldap statement::.
auth                   *Note auth statement::.
mailer                 *Note mailer statement::.

* Menu:

* MeTA1-lmtpd:: Using 'lmtpd' with MeTA1.


File: mailutils.info,  Node: MeTA1-lmtpd,  Up: lmtpd

3.13.1 Using 'lmtpd' with MeTA1.
--------------------------------

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

   The socket to listen for LMTP requests must be specified using the
'server' statement (*note Server Settings::).  For the purposes of this
section, let's suppose 'lmtpd' will listen on a UNIX socket
'/var/spool/meta1/lmtpsock'.  Then, the following (minimal) 'lmtpd'
configuration will do the job:

     # Run as daemon.
     mode daemon;
     # Switch to this group after startup.
     group meta1c;
     # Configure server:
     server unix:///var/spool/meta1/lmtpsock {
       transcript no;
     };

   To configure MeTA1 to use this socket, add the following statement to
the 'smtpc' section in '/etc/meta1/meta1.conf':

       LMTP_socket="lmtpsock";


File: mailutils.info,  Node: putmail,  Next: mimeview,  Prev: lmtpd,  Up: Programs

3.14 putmail
============

The 'putmail' utility reads a message from its standard input and
delivers it to the specified mailbox URL. The usage is:

     putmail URL

   For example, to deliver mail to a local mailbox
'/var/spool/mail/test':

     putmail /var/spool/mail/test

   Of course, this would work only it the 'test' mailbox is writable for
the user invoking 'putmail'.

   The 'smtp' mailbox scheme can be used for remote delivery.  For
example:

     putmail 'smtp://mail.example.org;to=ovr'

   The program will initiate SMTP dialog with the server
'mail.example.org' and will send the message from its standard input to
the user 'ovr' on that server.

* Menu:

* putmail options::
* putmail configuration::


File: mailutils.info,  Node: putmail options,  Next: putmail configuration,  Up: putmail

3.14.1 putmail options
----------------------

'-f EMAIL'
'-r EMAIL'
'--from=EMAIL'
     Specify the sender address.  If not used, the current user name
     will be used.

'-l NAME'
'--language=NAME'
     Define scripting language for the next '--script' option.  Valid
     arguments are 'sieve', 'scheme' and 'python'.

'--message-id-header=HEADER'
     Use this header to identify messages when logging Sieve actions

'-s NAME'
'--script=NAME'
     Set the name of the user-defined mail filter.  *Note MDA
     Scripting::, for a detailed discussion of the scripting feature.


File: mailutils.info,  Node: putmail configuration,  Prev: putmail options,  Up: putmail

3.14.2 putmail configuration
----------------------------

The behavior of 'putmail' is affected by the following configuration
statements:

Statement              Reference
-------------------------------------------------------------------
debug                  *Note debug statement::.
mailbox                *Note mailbox statement::.
locking                *Note locking statement::.
pam                    *Note pam statement::.
sql                    *Note sql statement::.
virtdomain             *Note virtdomain statement::.
radius                 *Note radius statement::.
ldap                   *Note ldap statement::.
auth                   *Note auth statement::.
mailer                 *Note mailer statement::.

   The utility also accepts all MDA configuration statements: *Note
Conf-mda::.


File: mailutils.info,  Node: mimeview,  Next: pop3d,  Prev: putmail,  Up: Programs

3.15 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, *note
(mime.types(5))mime.types::.  By default 'mimeview' searches for
'mime.types' in '$prefix/etc/cups/'(1), 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

* Menu:

* Mimeview Invocation::
* Mimeview Config::

   ---------- Footnotes ----------

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


File: mailutils.info,  Node: Mimeview Invocation,  Next: Mimeview Config,  Up: mimeview

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

     0
          Prints basic information about actions to be executed and
          reports about exit status of executed commands.

     1
          Additionally displays each file name along with its MIME type

     2
          Additionally traces the process of looking up the matching
          entry in 'mailcap' files.

     3
          Additionally, enables debugging of 'mime.types' parser ('g').

     4
          Additionally, enables debugging of 'mime.types' lexer ('l').

     digits from 5 to 9
          The same as 4, currently.

     If FLAGS are not given, the default '2' 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.

'-i'
'--identify'
     Identifies and prints the MIME type for each input file.

'-n'
'--dry-run'
     Do not do anything, just print what would be done.  Implies
     '--debug=1', unless the debugging level is set up explicitly.

'-f FILE'
'--mimetypes FILE'
     Use FILE as 'mime.types' file.  If FILE is a directory, use
     'FILE/mime.types'

'-t'
'--lint'
     Check syntax of the 'mime.types' file and exit.  Command line
     arguments are ignored.


File: mailutils.info,  Node: Mimeview Config,  Prev: Mimeview Invocation,  Up: mimeview

3.15.2 Mimeview Config
----------------------

The following configuration statements affect the behavior of
'mimeview':

Statement              Reference
-------------------------------------------------------------------
debug                  *Note Debug Statement::.

 -- Mimeview Config: mimetypes FILE
     Read FILE instead of the default 'mime.types'.

 -- Mimeview Config: metamail PROGRAM
     Use PROGRAM to display files.


File: mailutils.info,  Node: pop3d,  Next: imap4d,  Prev: mimeview,  Up: Programs

3.16 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 (*note
mode: Server Settings.).

* Menu:

* Login delay::
* Auto-expire::
* Bulletins::
* Conf-pop3d::           Pop3d Configuration
* Command line options::


File: mailutils.info,  Node: Login delay,  Next: Auto-expire,  Up: pop3d

3.16.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.17, 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.


File: mailutils.info,  Node: Auto-expire,  Next: Bulletins,  Prev: Login delay,  Up: pop3d

3.16.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'.


File: mailutils.info,  Node: Bulletins,  Next: Conf-pop3d,  Prev: Auto-expire,  Up: pop3d

3.16.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;


File: mailutils.info,  Node: Conf-pop3d,  Next: Command line options,  Prev: Bulletins,  Up: pop3d

3.16.4 Pop3d Configuration
--------------------------

The following configuration file statements affect the behavior of
'pop3d'.

Statement              Reference
-------------------------------------------------------------------
debug                  *Note debug statement::.
tls                    *Note tls statement::.
tls-file-checks        *Note tls-file-checks statement::.
mailbox                *Note mailbox statement::.
locking                *Note locking statement::.
logging                *Note logging statement::.
pam                    *Note pam statement::.
sql                    *Note sql statement::.
virtdomain             *Note virtdomain statement::.
radius                 *Note radius statement::.
ldap                   *Note ldap statement::.
auth                   *Note auth statement::.
server                 *Note Server Settings::.
acl                    *Note acl statement::.
tcp-wrappers           *Note tcp-wrappers statement::.

 -- Pop3d Conf: tls-mode MODE
     Configure the use of TLS encryption for inetd mode.

     In daemon mode, this statement sets the type of TLS encryption to
     use in all server blocks that lack the 'tls-mode' statement (*note
     Server Statement::).

     Allowed values for MODE are:

     no
          TLS is not used.  The 'STLS' command 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 (POP3S
          protocol).

 -- Pop3d Conf: undelete BOOL
     On startup, clear deletion marks from all the messages.

 -- Pop3d Conf: expire N
     Automatically expire read messages after N days.  *Note
     Auto-expire::, for a detailed description.

 -- Pop3d Conf: delete-expired BOOL
     Delete expired messages upon closing the mailbox.  *Note
     Auto-expire::, for a detailed description.

 -- Pop3d Conf: login-delay DURATION
     Set the minimal allowed delay between two successive logins.  *Note
     Login delay::, for more information.

 -- Pop3d Conf: stat-file FILE
     Set the name of login statistics file for the 'login-delay'
     facility.  *Note Login delay::, for more information.

 -- Pop3d Conf: bulletin-source FILE
     Get bulletins from the specified mailbox.  *Note Bulletins::, for a
     detailed description.

 -- Pop3d Conf: bulletin-db FILE
     Set bulletin database file name.  *Note Bulletins::, for a detailed
     description.


File: mailutils.info,  Node: Command line options,  Prev: Conf-pop3d,  Up: pop3d

3.16.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.  *Note Common
Options::.


File: mailutils.info,  Node: imap4d,  Next: comsatd,  Prev: pop3d,  Up: Programs

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

* Menu:

* Namespace::       Namespace.
* Conf-imap4d::     Configuration.
* Starting imap4d:: Invocation Options.


File: mailutils.info,  Node: Namespace,  Next: Conf-imap4d,  Up: imap4d

3.17.1 Namespace
----------------

GNU 'imap4d' supports a notion of "namespaces" defined in RFC 2342.  A
namespace can be regarded as a list of entities, defining locations to
which the user has certain access rights.  Each entity includes the
"prefix", under which the mailboxes can be found, "hierarchy delimiter",
a character used to delimit parts of a path to a mailbox, and a
"directory" on the file system on the server, which actually holds the
mailboxes.  Among these three values, only first two are visible to the
client using the IMAP 'NAMESPACE' command.

   There are three namespaces:

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.

     By default, this namespace contains a single prefix:

          prefix: ""
          delimiter: /
          directory: home directory of the user

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.

     By default, this namespace is empty.

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, this namespace is empty.

   The default values ensure that each user is able to see or otherwise
access mailboxes residing in the directories other than his own home.

   These defaults can be changed using the 'namespace' block statement:

     namespace NAME {
         mailbox-mode MODE;
         prefix PFX {
           directory PATH;
           delimiter CHR;
           mailbox-type TYPE;
         }
     }

   The NAME argument to the 'namespace' statement declares which
namespace is being configured.  Allowed values are: 'personal', 'other',
and 'shared'.

   The 'mailbox-mode' statement configures the file mode for the
mailboxes created within that namespace (provided that the directory
permissions allow the user to create mailboxes).  The MODE argument is a
comma-delimited list of symbolic mode settings, similar to that used by
'chmod'.  Each setting begins with a letter 'g', which means set mode
bits for file group, or 'o', which means set mode bits for other users
(note, that there is no 'u' specifier, since user ownership of his
mailbox cannot be changed).  This letter is followed by an '=' (or '+'),
and a list of modes to be set.  This list can contain only two letters:
'r' to set read permission, and 'w' to set write permission.

   For example, the following statement sets read and write permissions
for the group:

     mailbox-mode g=rw;

   The 'prefix' statement configures available prefixes and determines
their mappings to the server's file system.  The PFX argument defines
the prefix which will be visible to the IMAP client.

   The 'directory' statement defines the directory in the file system to
which PFX is mapped.  Exactly one 'directory' statement must be present
in each 'prefix' block.  The inerpretation of its argument depends on
the namespace in which it occurs.

   When used in the 'namespace shared' block, the argument to this
statement is interpreted verbatim, as an absolute pathname.

   When used in 'namespace personal' the argument to 'directory'
statement can contain references to the following variables (*note
Variables::):

user
     Login name of the user.

home
     Home directory of the user.

   For example, the following statement maps the default personal
namespace to the directory 'imap' in the user's home directory:

     namespace personal {
       prefix "";
       directory "$home/imap";
     }

   If the 'directory' statement is used within the 'namespace other'
block, its value can contain the '$user' and '$home' variables as well,
but their meaning is different.  For the 'other' namespace, the '$user'
variable is expanded to the part of the actual reference contained
between the prefix and first hierarchy delimiter (or the end of the
reference, if no delimiter occurs to the right of the prefix).
Correspondingly, '$home' expands to the home directory of that user.
Consider, for example, the following statement:

     namespace other {
       prefix "~";
       directory "/var/imap/$user";
     }

   If the client issues the following statement:

     1 LIST "~smith" "%"

then '$user' will expand to the string 'smith' and the server will look
for all mailboxes in the directory '/var/imap/smith'.

   The 'delimiter' statement defines the folder hierarchy delimiter for
that prefix.  It is optional, the default value being '"/"'.

   The 'mailbox-type' statement declares the type of the mailboxes
within that prefix.  If present, its argument must be a valid mailbox
type (e.g.  'mailbox', 'maildir', or 'mh').  The IMAP 'LIST' command
will display only mailboxes of that type.  The 'CREATE' command will
create mailboxes of that type.

   In the absence of the 'mailbox-type' statement, the IMAP 'LIST'
command will display mailboxes of any type supported by Mailutils.  The
type of newly-created mailboxes is then determined by the 'mailbox-type'
statement (*note mailbox-type::).

   Any number of 'prefix' blocks can be present.

   Consider, for example, the following configuration:

     namespace personal {
        prefix "" {
           directory "$home/mailfolder";
        }
        prefix "#MH:" {
           directory "$home/Mail";
           delimiter "/";
           mailbox-type "mh";
        }
     }

   It defines the personal namespace containing two prefixes.  The empty
prefix is mapped to the directory 'mailfolder' in the home directory of
the currently authenticated user.  Any type of mailboxes is supported
within that prefix.

   The prefix '#MH:' is mapped to the directory 'Mail' in the home
directory of the user, and is limited to contain only mailboxes in MH
format.

   Note that if the prefixes '""' is not defined in the personal
namespace, the following default will be automatically created:

     prefix "" {
       directory "$home";
     }

